@happyvertical/geo 0.74.8

package/dist/shared/types.d.ts

@@ -0,0 +1,233 @@
+/**
+ * Core types and interfaces for the Geo library
+ */
+/**
+ * Standardized location data structure
+ */
+export interface Location {
+    /**
+     * Unique identifier for the location (from provider)
+     */
+    id: string;
+    /**
+     * Type of location
+     */
+    type: 'country' | 'region' | 'city' | 'address' | 'point_of_interest' | 'unknown';
+    /**
+     * Full formatted name/address of the location
+     */
+    name: string;
+    /**
+     * Latitude coordinate
+     */
+    latitude: number;
+    /**
+     * Longitude coordinate
+     */
+    longitude: number;
+    /**
+     * Address components (all optional)
+     */
+    addressComponents: {
+        streetNumber?: string;
+        streetName?: string;
+        city?: string;
+        region?: string;
+        country?: string;
+        postalCode?: string;
+    };
+    /**
+     * ISO 3166-1 alpha-2 country code
+     */
+    countryCode: string;
+    /**
+     * Timezone identifier (optional, populated when provider returns it)
+     */
+    timezone?: string;
+    /**
+     * Raw response from the provider (for debugging or provider-specific data)
+     */
+    raw: any;
+}
+/**
+ * Options for POI (point-of-interest) searches.
+ *
+ * `types` and `keyword` are both forwarded to the backing provider but each
+ * provider interprets them slightly differently:
+ *
+ * - **Google**: `types[0]` becomes the request's `type` filter (Places API
+ *   accepts a single type per request; additional entries are ignored).
+ *   `keyword` is a free-text match across name/type/address/reviews.
+ * - **OpenStreetMap (Overpass)**: `types` are matched against
+ *   `amenity`, `shop`, and `tourism` tag values (e.g. `'cafe'`,
+ *   `'supermarket'`, `'museum'`). When omitted, the provider searches across
+ *   a broad set of POI-ish tag keys (`amenity`, `shop`, `tourism`,
+ *   `leisure`, `office`, `historic`). `keyword` is appended as a substring
+ *   filter on the `name` tag.
+ */
+export interface PoiSearchOptions {
+    /** Filter results to POIs matching these category values. See notes above. */
+    types?: string[];
+    /** Free-text keyword to narrow the search. */
+    keyword?: string;
+    /** Max results to return. Default 20. */
+    limit?: number;
+    /** Preferred language for place names (Google only). */
+    language?: string;
+}
+/**
+ * Geo provider interface - all providers must implement lookup and
+ * reverseGeocode. `findPoisNear` is optional — providers implement it when
+ * they support POI discovery beyond reverse geocoding. Callers that need to
+ * know whether a given instance supports POI search should feature-detect:
+ *
+ * ```ts
+ * if (typeof adapter.findPoisNear === 'function') { ... }
+ * ```
+ */
+export interface GeoProvider {
+    /**
+     * Look up locations based on a query string
+     * @param query - Search string (address, city, country, POI, etc.)
+     * @returns Promise resolving to array of matching Location objects
+     */
+    lookup(query: string): Promise<Location[]>;
+    /**
+     * Reverse geocode from coordinates to location
+     * @param latitude - Latitude coordinate
+     * @param longitude - Longitude coordinate
+     * @returns Promise resolving to array of matching Location objects
+     */
+    reverseGeocode(latitude: number, longitude: number): Promise<Location[]>;
+    /**
+     * Find POIs (point-of-interest places — businesses, landmarks, amenities)
+     * within a radius of a coordinate. Returns locations with
+     * `type: 'point_of_interest'` whose coords lie inside the requested
+     * radius, sorted by the provider's relevance ranking.
+     *
+     * @param latitude - Center latitude
+     * @param longitude - Center longitude
+     * @param radiusMeters - Search radius in meters
+     * @param options - Optional filters
+     * @returns Promise resolving to array of matching Location objects
+     */
+    findPoisNear?(latitude: number, longitude: number, radiusMeters: number, options?: PoiSearchOptions): Promise<Location[]>;
+}
+/**
+ * Geo adapter interface (structurally identical to GeoProvider)
+ */
+export interface GeoAdapter {
+    /**
+     * Look up locations based on a query string
+     * @param query - Search string (address, city, country, POI, etc.)
+     * @returns Promise resolving to array of matching Location objects
+     */
+    lookup(query: string): Promise<Location[]>;
+    /**
+     * Reverse geocode from coordinates to location
+     * @param latitude - Latitude coordinate
+     * @param longitude - Longitude coordinate
+     * @returns Promise resolving to array of matching Location objects
+     */
+    reverseGeocode(latitude: number, longitude: number): Promise<Location[]>;
+    /**
+     * Find POIs near a coordinate. Optional — see `GeoProvider.findPoisNear`.
+     */
+    findPoisNear?(latitude: number, longitude: number, radiusMeters: number, options?: PoiSearchOptions): Promise<Location[]>;
+}
+/**
+ * Base configuration options for all providers
+ */
+export interface BaseGeoOptions {
+    /**
+     * Request timeout in milliseconds
+     */
+    timeout?: number;
+    /**
+     * Maximum number of results to return
+     */
+    maxResults?: number;
+}
+/**
+ * Google Maps provider options
+ */
+export interface GoogleMapsOptions extends BaseGeoOptions {
+    provider: 'google';
+    /**
+     * Google Maps API key
+     */
+    apiKey: string;
+}
+/**
+ * OpenStreetMap provider options
+ */
+export interface OpenStreetMapOptions extends BaseGeoOptions {
+    provider: 'openstreetmap';
+    /**
+     * Custom User-Agent for OSM requests (optional, defaults to package name)
+     */
+    userAgent?: string;
+    /**
+     * Rate limit delay in milliseconds (default: 1000ms for 1 req/sec)
+     */
+    rateLimitDelay?: number;
+}
+/**
+ * Union type for all provider options
+ */
+export type GeoAdapterOptions = GoogleMapsOptions | OpenStreetMapOptions;
+/**
+ * Base error class for geo operations.
+ * All geo-specific errors extend this class and include a machine-readable `code`
+ * and the `provider` name that produced the error.
+ */
+export declare class GeoError extends Error {
+    code: string;
+    provider?: string | undefined;
+    /**
+     * @param message - Human-readable error description
+     * @param code - Machine-readable error code (e.g. 'RATE_LIMIT', 'AUTH_ERROR')
+     * @param provider - Provider that raised the error ('google' | 'openstreetmap')
+     */
+    constructor(message: string, code: string, provider?: string | undefined);
+}
+/**
+ * Thrown when the provider's rate limit has been exceeded.
+ */
+export declare class RateLimitError extends GeoError {
+    /**
+     * @param provider - Provider that raised the error
+     * @param retryAfter - Seconds to wait before retrying (if known)
+     */
+    constructor(provider?: string, retryAfter?: number);
+}
+/**
+ * Thrown when the geocoding query is empty or malformed.
+ */
+export declare class InvalidQueryError extends GeoError {
+    /**
+     * @param query - The invalid query string
+     * @param provider - Provider that raised the error
+     */
+    constructor(query: string, provider?: string);
+}
+/**
+ * Thrown when the provider rejects the API key or credentials.
+ */
+export declare class AuthenticationError extends GeoError {
+    /**
+     * @param provider - Provider that raised the error
+     */
+    constructor(provider?: string);
+}
+/**
+ * Thrown when a geocoding query returns zero results.
+ */
+export declare class NoResultsError extends GeoError {
+    /**
+     * @param query - The query that produced no results
+     * @param provider - Provider that raised the error
+     */
+    constructor(query: string, provider?: string);
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shared/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/shared/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,QAAQ;IACvB;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IAEX;;OAEG;IACH,IAAI,EACA,SAAS,GACT,QAAQ,GACR,MAAM,GACN,SAAS,GACT,mBAAmB,GACnB,SAAS,CAAC;IAEd;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,iBAAiB,EAAE;QACjB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;KACrB,CAAC;IAEF;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;OAEG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,GAAG,EAAE,GAAG,CAAC;CACV;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,8CAA8C;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEzE;;;;;;;;;;;OAWG;IACH,YAAY,CAAC,CACX,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAE3C;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;IAEzE;;OAEG;IACH,YAAY,CAAC,CACX,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,QAAQ,EAAE,QAAQ,CAAC;IACnB;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,QAAQ,EAAE,eAAe,CAAC;IAC1B;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;OAEG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AAEzE;;;;GAIG;AACH,qBAAa,QAAS,SAAQ,KAAK;IAQxB,IAAI,EAAE,MAAM;IACZ,QAAQ,CAAC,EAAE,MAAM;IAR1B;;;;OAIG;gBAED,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,QAAQ,CAAC,EAAE,MAAM,YAAA;CAK3B;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C;;;OAGG;gBACS,QAAQ,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM;CAQnD;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C;;;OAGG;gBACS,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;CAI7C;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IAC/C;;OAEG;gBACS,QAAQ,CAAC,EAAE,MAAM;CAI9B;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IAC1C;;;OAGG;gBACS,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM;CAI7C"}

package/dist/shared/utils.d.ts

@@ -0,0 +1,52 @@
+import { Location } from './types';
+/**
+ * Map Google Maps place types to standardized location types.
+ * Checks types in priority order: address, city, region, country, point_of_interest.
+ *
+ * @param types - Array of Google Maps place type strings (e.g. 'street_address', 'locality')
+ * @returns The standardized location type
+ */
+export declare function mapGooglePlaceType(types: string[]): Location['type'];
+/**
+ * Map OpenStreetMap place types to standardized location types.
+ * Uses both the Nominatim `type` and `addresstype` fields for classification.
+ *
+ * @param type - Nominatim result type (e.g. 'house', 'city', 'state')
+ * @param addressType - Nominatim addresstype field (optional secondary classifier)
+ * @returns The standardized location type
+ */
+export declare function mapOSMPlaceType(type: string, addressType?: string): Location['type'];
+/**
+ * Normalize a country code to uppercase ISO 3166-1 format.
+ * Returns 'XX' for undefined, empty, or unrecognized inputs.
+ *
+ * @param code - Country code string (alpha-2 or alpha-3)
+ * @returns Uppercase country code, or 'XX' if unknown
+ */
+export declare function normalizeCountryCode(code: string | undefined): string;
+/**
+ * Validate that a latitude value is within the valid range (-90 to 90).
+ *
+ * @param lat - Latitude value to validate
+ * @returns `true` if the value is a number between -90 and 90 inclusive
+ */
+export declare function isValidLatitude(lat: number): boolean;
+/**
+ * Validate that a longitude value is within the valid range (-180 to 180).
+ *
+ * @param lng - Longitude value to validate
+ * @returns `true` if the value is a number between -180 and 180 inclusive
+ */
+export declare function isValidLongitude(lng: number): boolean;
+/**
+ * Validate that both latitude and longitude are within their valid ranges.
+ *
+ * @param latitude - Latitude value (-90 to 90)
+ * @param longitude - Longitude value (-180 to 180)
+ * @returns Object with `valid: true` if both are valid, or `valid: false` with an `error` message
+ */
+export declare function validateCoordinates(latitude: number, longitude: number): {
+    valid: boolean;
+    error?: string;
+};
+//# sourceMappingURL=utils.d.ts.map

package/dist/shared/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/shared/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAExC;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC,MAAM,CAAC,CAwBpE;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,QAAQ,CAAC,MAAM,CAAC,CA+ClB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAcrE;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEpD;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAErD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAgBpC"}

package/dist/static-maps.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Static Map Generation
+ *
+ * Generates static map URLs and fetches map images for location-based content.
+ * Supports Mapbox and Google Maps providers.
+ *
+ * @example
+ * ```typescript
+ * import { getStaticMapUrl, fetchStaticMap } from '@happyvertical/geo';
+ *
+ * // Get URL for embedding
+ * const url = getStaticMapUrl(53.5461, -113.4938, {
+ *   provider: 'mapbox',
+ *   zoom: 14,
+ *   width: 1200,
+ *   height: 630
+ * });
+ *
+ * // Fetch the actual image
+ * const buffer = await fetchStaticMap(53.5461, -113.4938, {
+ *   provider: 'mapbox'
+ * });
+ * await writeFile('map.png', buffer);
+ * ```
+ */
+/**
+ * Static map provider
+ */
+export type StaticMapProvider = 'mapbox' | 'google';
+/**
+ * Mapbox map styles
+ * @see https://docs.mapbox.com/api/maps/styles/
+ */
+export type MapboxStyle = 'streets-v12' | 'outdoors-v12' | 'light-v11' | 'dark-v11' | 'satellite-v9' | 'satellite-streets-v12';
+/**
+ * Google Maps map types
+ * @see https://developers.google.com/maps/documentation/maps-static/start
+ */
+export type GoogleMapType = 'roadmap' | 'satellite' | 'terrain' | 'hybrid';
+/**
+ * Marker definition for the map
+ */
+export interface StaticMapMarker {
+    /** Latitude */
+    latitude: number;
+    /** Longitude */
+    longitude: number;
+    /** Marker color (hex or named color) */
+    color?: string;
+    /** Marker label (single character for Google, any for Mapbox) */
+    label?: string;
+    /** Marker size ('small' | 'medium' | 'large') */
+    size?: 'small' | 'medium' | 'large';
+}
+/**
+ * Options for static map generation
+ */
+export interface StaticMapOptions {
+    /**
+     * Map provider
+     * @default 'mapbox'
+     */
+    provider?: StaticMapProvider;
+    /**
+     * Image width in pixels
+     * @default 1200
+     */
+    width?: number;
+    /**
+     * Image height in pixels
+     * @default 630
+     */
+    height?: number;
+    /**
+     * Zoom level (1-20)
+     * @default 14
+     */
+    zoom?: number;
+    /**
+     * Marker color (hex without # or named color)
+     * @default 'e74c3c' (red)
+     */
+    markerColor?: string;
+    /**
+     * Show a marker at the center point
+     * @default true
+     */
+    showMarker?: boolean;
+    /**
+     * Mapbox access token (required for Mapbox provider)
+     * Falls back to MAPBOX_ACCESS_TOKEN env var
+     */
+    mapboxToken?: string;
+    /**
+     * Google Maps API key (required for Google provider)
+     * Falls back to GOOGLE_MAPS_API_KEY env var
+     */
+    googleApiKey?: string;
+    /**
+     * Mapbox style
+     * @default 'streets-v12'
+     */
+    mapboxStyle?: MapboxStyle;
+    /**
+     * Google map type
+     * @default 'roadmap'
+     */
+    googleMapType?: GoogleMapType;
+    /**
+     * Pixel density (1 or 2 for retina)
+     * @default 1
+     */
+    scale?: 1 | 2;
+    /**
+     * Additional markers to display
+     */
+    markers?: StaticMapMarker[];
+}
+/**
+ * Result from fetching a static map
+ */
+export interface StaticMapResult {
+    /** PNG image buffer */
+    buffer: Buffer;
+    /** Image width */
+    width: number;
+    /** Image height */
+    height: number;
+    /** MIME type */
+    mimeType: 'image/png';
+    /** The URL that was fetched */
+    url: string;
+}
+/**
+ * Generate a static map URL
+ *
+ * Returns a URL that can be used directly in <img> tags or fetched for processing.
+ *
+ * @param latitude - Center latitude
+ * @param longitude - Center longitude
+ * @param options - Map options
+ * @returns URL string for the static map
+ *
+ * @example Mapbox (default)
+ * ```typescript
+ * const url = getStaticMapUrl(53.5461, -113.4938, {
+ *   provider: 'mapbox',
+ *   zoom: 14,
+ *   mapboxStyle: 'streets-v12'
+ * });
+ * ```
+ *
+ * @example Google Maps
+ * ```typescript
+ * const url = getStaticMapUrl(53.5461, -113.4938, {
+ *   provider: 'google',
+ *   zoom: 14,
+ *   googleMapType: 'roadmap'
+ * });
+ * ```
+ *
+ * @example With custom markers
+ * ```typescript
+ * const url = getStaticMapUrl(53.5461, -113.4938, {
+ *   showMarker: false,  // Hide center marker
+ *   markers: [
+ *     { latitude: 53.5461, longitude: -113.4938, color: 'blue', label: 'A' },
+ *     { latitude: 53.5500, longitude: -113.4900, color: 'green', label: 'B' }
+ *   ]
+ * });
+ * ```
+ */
+export declare function getStaticMapUrl(latitude: number, longitude: number, options?: StaticMapOptions): string;
+/**
+ * Fetch a static map image
+ *
+ * Downloads the map image and returns it as a Buffer.
+ *
+ * @param latitude - Center latitude
+ * @param longitude - Center longitude
+ * @param options - Map options
+ * @returns Promise resolving to the map image result
+ *
+ * @example
+ * ```typescript
+ * const result = await fetchStaticMap(53.5461, -113.4938, {
+ *   provider: 'mapbox',
+ *   width: 1200,
+ *   height: 630
+ * });
+ *
+ * await fs.writeFile('map.png', result.buffer);
+ * console.log(`Fetched ${result.width}x${result.height} map`);
+ * ```
+ */
+export declare function fetchStaticMap(latitude: number, longitude: number, options?: StaticMapOptions): Promise<StaticMapResult>;
+/**
+ * Generate OG-sized static map URL (1200x630)
+ *
+ * Convenience function for generating Open Graph / social media sized maps.
+ *
+ * @param latitude - Center latitude
+ * @param longitude - Center longitude
+ * @param options - Map options (width/height ignored, set to 1200x630)
+ * @returns URL string for the static map
+ *
+ * @example
+ * ```typescript
+ * const url = getOGMapUrl(53.5461, -113.4938);
+ * // Returns 1200x630 map URL
+ * ```
+ */
+export declare function getOGMapUrl(latitude: number, longitude: number, options?: Omit<StaticMapOptions, 'width' | 'height'>): string;
+//# sourceMappingURL=static-maps.d.ts.map

package/dist/static-maps.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"static-maps.d.ts","sourceRoot":"","sources":["../src/static-maps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,aAAa,GACb,cAAc,GACd,WAAW,GACX,UAAU,GACV,cAAc,GACd,uBAAuB,CAAC;AAE5B;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE3E;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,IAAI,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;CACrC;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAE7B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IAErB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB;;;OAGG;IACH,WAAW,CAAC,EAAE,WAAW,CAAC;IAE1B;;;OAGG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAE9B;;;OAGG;IACH,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEd;;OAEG;IACH,OAAO,CAAC,EAAE,eAAe,EAAE,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uBAAuB;IACvB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB;IAChB,QAAQ,EAAE,WAAW,CAAC;IACtB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;CACb;AAmHD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,gBAAqB,GAC7B,MAAM,CAUR;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC,eAAe,CAAC,CAwB1B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,GAAG,QAAQ,CAAM,GACvD,MAAM,CAMR"}

package/metadata.json

@@ -0,0 +1,31 @@
+{
+  "name": "@happyvertical/geo",
+  "path": "packages/geo",
+  "position": {
+    "index": 12,
+    "count": 30
+  },
+  "description": "Standardized geographical information interface supporting Google Maps and OpenStreetMap",
+  "provides": [
+    "Standardized geographical information interface supporting Google Maps and OpenStreetMap"
+  ],
+  "implements": [],
+  "requires": {
+    "workspace": [
+      "@happyvertical/cache",
+      "@happyvertical/utils"
+    ],
+    "externalHappyVertical": [],
+    "external": [
+      "@googlemaps/google-maps-services-js"
+    ]
+  },
+  "dependents": [],
+  "stability": {
+    "level": "stable",
+    "reason": "Primary package surface is described as implemented and production-oriented."
+  },
+  "keywords": [
+    "geo"
+  ]
+}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@happyvertical/geo",
+  "version": "0.74.8",
+  "description": "Standardized geographical information interface supporting Google Maps and OpenStreetMap",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "have-geo-context": "./dist/cli/claude-context.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "AGENT.md",
+    "metadata.json"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/sdk.git",
+    "directory": "packages/geo"
+  },
+  "bugs": {
+    "url": "https://github.com/happyvertical/sdk/issues"
+  },
+  "homepage": "https://github.com/happyvertical/sdk/tree/main/packages/geo#readme",
+  "keywords": [
+    "geocoding",
+    "maps",
+    "location",
+    "google-maps",
+    "openstreetmap",
+    "nominatim"
+  ],
+  "author": "willgriffin@gmail.com",
+  "license": "ISC",
+  "dependencies": {
+    "@googlemaps/google-maps-services-js": "^3.4.2",
+    "@happyvertical/cache": "0.74.8",
+    "@happyvertical/utils": "0.74.8"
+  },
+  "devDependencies": {
+    "@types/node": "25.0.10",
+    "typescript": "^5.9.3",
+    "vite": "7.3.2",
+    "vite-plugin-dts": "4.5.4",
+    "vitest": "^4.1.5"
+  },
+  "scripts": {
+    "test": "npx vitest run",
+    "test:watch": "npx vitest",
+    "build": "vite build",
+    "build:watch": "vite build --watch",
+    "docs": "typedoc --plugin typedoc-plugin-markdown --out docs --entryPoints ./src/index.ts --tsconfig ./tsconfig.json --excludePrivate --excludeInternal --hideGenerator --fileExtension .md --readme none --categorizeByGroup false --includeVersion false --hidePageHeader --hidePageTitle false --outputFileStrategy modules",
+    "docs:watch": "typedoc --plugin typedoc-plugin-markdown --out docs --entryPoints ./src/index.ts --tsconfig ./tsconfig.json --excludePrivate --excludeInternal --hideGenerator --fileExtension .md --readme none --categorizeByGroup false --includeVersion false --hidePageHeader --hidePageTitle false --outputFileStrategy modules --watch",
+    "clean": "rm -rf dist docs *.tsbuildinfo",
+    "dev": "npm run build:watch & npm run test:watch"
+  }
+}