@jmruthers/pace-core 0.5.186 → 0.5.187

package/src/utils/google-places/googlePlacesUtils.ts

@@ -0,0 +1,475 @@
+/**
+ * @file Google Places API Utilities
+ * @package @jmruthers/pace-core
+ * @module Utils/GooglePlaces
+ * @since 0.1.0
+ *
+ * Utility functions for interacting with Google Places API.
+ * Uses the Google Maps JavaScript API to avoid CORS issues.
+ *
+ * Features:
+ * - Places Autocomplete Service integration
+ * - Places Service integration
+ * - Address component parsing
+ * - Error handling
+ * - Request deduplication
+ */
+
+import { getOrCreateRequest } from '../request-deduplication';
+import { createLogger } from '../core/logger';
+import { loadGoogleMapsScript, isGoogleMapsLoaded } from './loadGoogleMapsScript';
+import type {
+  GooglePlaceAutocompletePrediction,
+  ParsedAddress,
+  AutocompleteOptions,
+} from './types';
+
+const log = createLogger('google-places');
+
+// Google Maps types are defined in loadGoogleMapsScript.ts
+
+/**
+ * Fetch place autocomplete predictions using Google Maps JavaScript API
+ *
+ * @param query - Search query string
+ * @param apiKey - Google Places API key
+ * @param options - Optional autocomplete options
+ * @returns Promise resolving to array of predictions
+ *
+ * @example
+ * ```ts
+ * const predictions = await fetchPlaceAutocomplete(
+ *   '123 Main St',
+ *   'your-api-key',
+ *   { components: 'country:au' }
+ * );
+ * ```
+ */
+export async function fetchPlaceAutocomplete(
+  query: string,
+  apiKey: string,
+  options?: AutocompleteOptions
+): Promise<GooglePlaceAutocompletePrediction[]> {
+  if (!query.trim()) {
+    return [];
+  }
+
+  if (!apiKey) {
+    throw new Error('Google Places API key is required');
+  }
+
+  // Ensure Google Maps script is loaded
+  if (!isGoogleMapsLoaded()) {
+    await loadGoogleMapsScript(apiKey, 'places');
+  }
+
+  const requestKey = `google-places-autocomplete:${query}:${JSON.stringify(options || {})}`;
+
+  return getOrCreateRequest(requestKey, async () => {
+    try {
+      log.debug(`Fetching autocomplete for query: ${query}`);
+
+      if (!window.google?.maps?.places) {
+        throw new Error('Google Maps Places library not available');
+      }
+
+      // Try to use the new AutocompleteSuggestion API first, fallback to legacy AutocompleteService
+      const useNewAPI = window.google.maps.places.AutocompleteSuggestion !== undefined;
+      
+      if (useNewAPI) {
+        // Use new AutocompleteSuggestion API
+        const request: {
+          input: string;
+          includedRegionCodes?: string[];
+          locationBias?: {
+            circle?: {
+              center: { latitude: number; longitude: number };
+              radius: number;
+            };
+          };
+          includedPrimaryTypes?: string[];
+          languageCode?: string;
+        } = {
+          input: query.trim(),
+        };
+
+        // Parse components option (e.g., "country:au" -> ["au"])
+        if (options?.components) {
+          const componentParts = options.components.split('|');
+          const countries: string[] = [];
+
+          componentParts.forEach((part) => {
+            const [key, value] = part.split(':');
+            if (key === 'country') {
+              countries.push(...value.split(',').map(c => c.toUpperCase()));
+            }
+          });
+
+          if (countries.length > 0) {
+            request.includedRegionCodes = countries;
+          }
+        }
+
+        if (options?.location && options?.radius) {
+          const [lat, lng] = options.location.split(',').map(Number);
+          request.locationBias = {
+            circle: {
+              center: { latitude: lat, longitude: lng },
+              radius: options.radius,
+            },
+          };
+        }
+
+        if (options?.language) {
+          request.languageCode = options.language;
+        }
+
+        // Call new API
+        return new Promise<GooglePlaceAutocompletePrediction[]>((resolve, reject) => {
+          window.google!.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request)
+            .then((response) => {
+              if (response.suggestions && response.suggestions.length > 0) {
+                const result: GooglePlaceAutocompletePrediction[] = response.suggestions
+                  .filter(s => s.placePrediction)
+                  .map((s) => ({
+                    description: s.placePrediction!.text.text,
+                    place_id: s.placePrediction!.placeId,
+                    structured_formatting: {
+                      main_text: s.placePrediction!.structuredFormat?.mainText?.text || s.placePrediction!.text.text,
+                      secondary_text: s.placePrediction!.structuredFormat?.secondaryText?.text || '',
+                    },
+                  }));
+                log.debug(`Received ${result.length} predictions (new API)`);
+                resolve(result);
+              } else {
+                log.debug('No results found (new API)');
+                resolve([]);
+              }
+            })
+            .catch((error) => {
+              log.error('Autocomplete fetch failed (new API):', error);
+              reject(new Error(`Failed to fetch autocomplete predictions: ${error.message || 'Unknown error'}`));
+            });
+        });
+      }
+
+      // Fallback to legacy AutocompleteService
+      const autocompleteService = new window.google.maps.places.AutocompleteService();
+
+      // Build request
+      const request: {
+        input: string;
+        componentRestrictions?: { country: string | string[] };
+        location?: { lat: () => number; lng: () => number };
+        radius?: number;
+        types?: string[];
+        language?: string;
+      } = {
+        input: query.trim(),
+      };
+
+      // Parse components option (e.g., "country:au" -> { country: "AU" })
+      if (options?.components) {
+        const componentParts = options.components.split('|');
+        const restrictions: { country?: string[] } = {};
+        const countries: string[] = [];
+
+        componentParts.forEach((part) => {
+          const [key, value] = part.split(':');
+          if (key === 'country') {
+            // Convert to uppercase for consistency with Google Maps API
+            countries.push(...value.split(',').map(c => c.toUpperCase()));
+          }
+        });
+
+        if (countries.length > 0) {
+          request.componentRestrictions = { country: countries.length === 1 ? countries[0] : countries };
+        }
+      }
+
+      if (options?.location) {
+        const [lat, lng] = options.location.split(',').map(Number);
+        if (window.google?.maps?.LatLng) {
+          request.location = new window.google.maps.LatLng(lat, lng);
+        }
+      }
+
+      if (options?.radius) {
+        request.radius = options.radius;
+      }
+
+      if (options?.types) {
+        request.types = [options.types];
+      }
+
+      if (options?.language) {
+        request.language = options.language;
+      }
+
+      // Call AutocompleteService
+      return new Promise<GooglePlaceAutocompletePrediction[]>((resolve, reject) => {
+        autocompleteService.getPlacePredictions(request, (predictions, status) => {
+          if (status === 'OK' && predictions) {
+            log.debug(`Received ${predictions.length} predictions`);
+            // Convert to our format
+            const result: GooglePlaceAutocompletePrediction[] = predictions.map((pred) => ({
+              description: pred.description,
+              place_id: pred.place_id,
+              structured_formatting: {
+                main_text: pred.structured_formatting.main_text,
+                secondary_text: pred.structured_formatting.secondary_text,
+              },
+            }));
+            resolve(result);
+          } else if (status === 'ZERO_RESULTS') {
+            log.debug('No results found');
+            resolve([]);
+          } else {
+            const errorMsg = `Google Places API error: ${status}`;
+            log.error('Autocomplete fetch failed:', errorMsg);
+            reject(new Error(errorMsg));
+          }
+        });
+      });
+    } catch (error) {
+      if (error instanceof Error) {
+        log.error('Autocomplete fetch failed:', error.message);
+        throw error;
+      }
+      log.error('Autocomplete fetch failed: Unknown error');
+      throw new Error('Failed to fetch autocomplete predictions');
+    }
+  });
+}
+
+/**
+ * Fetch place details from Google Places API
+ *
+ * @param placeId - Google Place ID
+ * @param apiKey - Google Places API key
+ * @returns Promise resolving to place details
+ *
+ * @example
+ * ```ts
+ * const place = await fetchPlaceDetails('ChIJ...', 'your-api-key');
+ * ```
+ */
+export async function fetchPlaceDetails(
+  placeId: string,
+  apiKey: string
+): Promise<{
+  place_id: string;
+  formatted_address?: string;
+  address_components?: Array<{
+    long_name: string;
+    short_name: string;
+    types: string[];
+  }>;
+  geometry?: {
+    location?: {
+      lat: () => number;
+      lng: () => number;
+    };
+  };
+}> {
+  if (!placeId) {
+    throw new Error('Place ID is required');
+  }
+
+  if (!apiKey) {
+    throw new Error('Google Places API key is required');
+  }
+
+  // Ensure Google Maps script is loaded
+  if (!isGoogleMapsLoaded()) {
+    await loadGoogleMapsScript(apiKey, 'places');
+  }
+
+  const requestKey = `google-places-details:${placeId}`;
+
+  return getOrCreateRequest(requestKey, async () => {
+    try {
+      log.debug(`Fetching place details for place_id: ${placeId}`);
+
+      if (!window.google?.maps?.places) {
+        throw new Error('Google Maps Places library not available');
+      }
+
+      // Create a dummy element for PlacesService (it needs an element but we don't use it)
+      const dummyElement = document.createElement('div');
+      const placesService = new window.google.maps.places.PlacesService(dummyElement);
+
+      // Call getDetails
+      return new Promise<{
+        place_id: string;
+        formatted_address?: string;
+        address_components?: Array<{
+          long_name: string;
+          short_name: string;
+          types: string[];
+        }>;
+        geometry?: {
+          location?: {
+            lat: () => number;
+            lng: () => number;
+          };
+        };
+      }>((resolve, reject) => {
+        placesService.getDetails(
+          {
+            placeId: placeId,
+            fields: ['place_id', 'formatted_address', 'address_components', 'geometry'],
+          },
+          (place, status) => {
+            if (status === 'OK' && place) {
+              log.debug('Place details fetched successfully');
+              resolve(place as any);
+            } else if (status === 'NOT_FOUND') {
+              log.error('Place not found:', placeId);
+              reject(new Error('Place not found'));
+            } else {
+              const errorMsg = `Failed to fetch place details: ${status}`;
+              log.error('Place details fetch failed:', errorMsg);
+              reject(new Error(errorMsg));
+            }
+          }
+        );
+      });
+    } catch (error) {
+      if (error instanceof Error) {
+        log.error('Place details fetch failed:', error.message);
+        throw error;
+      }
+      log.error('Place details fetch failed: Unknown error');
+      throw new Error('Failed to fetch place details');
+    }
+  });
+}
+
+/**
+ * Parse address components from Google Places API response
+ *
+ * @param components - Array of address components from Google API
+ * @returns Parsed address components
+ */
+export function parseAddressComponents(
+  components: Array<{
+    long_name: string;
+    short_name: string;
+    types: string[];
+  }> | undefined
+): {
+  street_number: string | null;
+  route: string | null;
+  suburb: string | null;
+  state: string | null;
+  postcode: string | null;
+  country: string | null;
+} {
+  if (!components || components.length === 0) {
+    return {
+      street_number: null,
+      route: null,
+      suburb: null,
+      state: null,
+      postcode: null,
+      country: null,
+    };
+  }
+
+  const result = {
+    street_number: null as string | null,
+    route: null as string | null,
+    suburb: null as string | null,
+    state: null as string | null,
+    postcode: null as string | null,
+    country: null as string | null,
+  };
+
+  for (const component of components) {
+    const types = component.types || [];
+
+    if (types.includes('street_number')) {
+      result.street_number = component.long_name;
+    } else if (types.includes('route')) {
+      result.route = component.long_name;
+    } else if (types.includes('locality') || types.includes('sublocality')) {
+      result.suburb = component.long_name;
+    } else if (types.includes('administrative_area_level_1')) {
+      result.state = component.short_name;
+    } else if (types.includes('postal_code')) {
+      result.postcode = component.long_name;
+    } else if (types.includes('country')) {
+      result.country = component.short_name;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Create parsed address from Google Places API place result
+ *
+ * @param place - Place result from Google Places Details API
+ * @returns Parsed address matching pace_address table structure
+ */
+export function createAddressFromPlaceResult(
+  place: {
+    place_id: string;
+    formatted_address?: string;
+    address_components?: Array<{
+      long_name: string;
+      short_name: string;
+      types: string[];
+    }>;
+    geometry?: {
+      location?: {
+        lat: () => number;
+        lng: () => number;
+      };
+    };
+  }
+): ParsedAddress {
+  const components = parseAddressComponents(place.address_components || []);
+
+  return {
+    place_id: place.place_id,
+    full_address: place.formatted_address || null,
+    street_number: components.street_number,
+    route: components.route,
+    suburb: components.suburb,
+    state: components.state,
+    postcode: components.postcode,
+    country: components.country,
+    lat: place.geometry?.location?.lat() ?? null,
+    lng: place.geometry?.location?.lng() ?? null,
+  };
+}
+
+/**
+ * Get full address details by place_id
+ * Useful for retrieving address from stored place_id without autocomplete search
+ *
+ * @param placeId - Google Place ID
+ * @param apiKey - Google Places API key
+ * @returns Promise resolving to parsed address
+ *
+ * @example
+ * ```ts
+ * const address = await getAddressByPlaceId('ChIJ...', 'your-api-key');
+ * // Returns: { place_id: 'ChIJ...', full_address: '...', ... }
+ * ```
+ */
+export async function getAddressByPlaceId(
+  placeId: string,
+  apiKey: string
+): Promise<ParsedAddress | null> {
+  try {
+    const place = await fetchPlaceDetails(placeId, apiKey);
+    return createAddressFromPlaceResult(place);
+  } catch (error) {
+    log.error('Failed to get address by place_id:', error);
+    return null;
+  }
+}
+

package/src/utils/google-places/index.ts

@@ -0,0 +1,26 @@
+/**
+ * @file Google Places API Utilities Exports
+ * @package @jmruthers/pace-core
+ * @module Utils/GooglePlaces
+ * @since 0.1.0
+ */
+
+export {
+  fetchPlaceAutocomplete,
+  fetchPlaceDetails,
+  parseAddressComponents,
+  createAddressFromPlaceResult,
+  getAddressByPlaceId,
+} from './googlePlacesUtils';
+
+export {
+  loadGoogleMapsScript,
+  isGoogleMapsLoaded,
+} from './loadGoogleMapsScript';
+
+export type {
+  GooglePlaceAutocompletePrediction,
+  ParsedAddress,
+  AutocompleteOptions,
+} from './types';
+

package/src/utils/google-places/loadGoogleMapsScript.ts

@@ -0,0 +1,207 @@
+/**
+ * @file Google Maps Script Loader
+ * @package @jmruthers/pace-core
+ * @module Utils/GooglePlaces
+ * @since 0.1.0
+ *
+ * Utility to dynamically load the Google Maps JavaScript API.
+ * This is required because the REST API doesn't support CORS from browsers.
+ */
+
+// Type definitions for Google Maps (minimal, just what we need)
+declare global {
+  interface Window {
+    google?: {
+      maps: {
+        places: {
+          // New AutocompleteSuggestion API (recommended)
+          AutocompleteSuggestion: {
+            fetchAutocompleteSuggestions: (
+              request: {
+                input: string;
+                includedRegionCodes?: string[];
+                locationBias?: {
+                  circle?: {
+                    center: { latitude: number; longitude: number };
+                    radius: number;
+                  };
+                };
+                includedPrimaryTypes?: string[];
+                languageCode?: string;
+              }
+            ) => Promise<{
+              suggestions: Array<{
+                placePrediction?: {
+                  placeId: string;
+                  text: {
+                    text: string;
+                    matches: Array<{
+                      endOffset: number;
+                      startOffset: number;
+                    }>;
+                  };
+                  structuredFormat?: {
+                    mainText: { text: string };
+                    secondaryText: { text: string };
+                  };
+                };
+              }>;
+            }>;
+          };
+          // Legacy AutocompleteService (deprecated but still works)
+          AutocompleteService: new () => {
+            getPlacePredictions: (
+              request: {
+                input: string;
+                componentRestrictions?: { country: string | string[] };
+                location?: { lat: () => number; lng: () => number };
+                radius?: number;
+                types?: string[];
+                language?: string;
+              },
+              callback: (
+                predictions: Array<{
+                  description: string;
+                  place_id: string;
+                  structured_formatting: {
+                    main_text: string;
+                    secondary_text: string;
+                  };
+                }> | null,
+                status: string
+              ) => void
+            ) => void;
+          };
+          PlacesService: new (element: HTMLElement) => {
+            getDetails: (
+              request: { placeId: string; fields?: string[] },
+              callback: (
+                place: {
+                  place_id: string;
+                  formatted_address?: string;
+                  address_components?: Array<{
+                    long_name: string;
+                    short_name: string;
+                    types: string[];
+                  }>;
+                  geometry?: {
+                    location?: {
+                      lat: () => number;
+                      lng: () => number;
+                    };
+                  };
+                } | null,
+                status: string
+              ) => void
+            ) => void;
+          };
+          PlacesServiceStatus: {
+            OK: string;
+            ZERO_RESULTS: string;
+            NOT_FOUND: string;
+            REQUEST_DENIED: string;
+            INVALID_REQUEST: string;
+            OVER_QUERY_LIMIT: string;
+          };
+        };
+        LatLng: new (lat: number, lng: number) => { lat: () => number; lng: () => number };
+      };
+    };
+  }
+}
+
+/**
+ * Load Google Maps JavaScript API script
+ * @param apiKey - Google Places API key
+ * @param libraries - Comma-separated list of libraries to load (default: 'places')
+ * @returns Promise that resolves when the script is loaded
+ */
+export function loadGoogleMapsScript(
+  apiKey: string,
+  libraries: string = 'places'
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    // Check if script is already loaded
+    if (window.google && window.google.maps && window.google.maps.places) {
+      resolve();
+      return;
+    }
+
+    // Check if script is already being loaded
+    const existingScript = document.querySelector(
+      `script[src*="maps.googleapis.com/maps/api/js"]`
+    );
+    if (existingScript) {
+      // Wait for existing script to load
+      existingScript.addEventListener('load', () => {
+        // Wait for the library to initialize with multiple retries
+        let attempts = 0;
+        const maxAttempts = 20; // 2 seconds total
+        
+        const checkPlaces = () => {
+          if (window.google?.maps?.places) {
+            resolve();
+          } else if (attempts < maxAttempts) {
+            attempts++;
+            setTimeout(checkPlaces, 100);
+          } else {
+            reject(new Error('Google Maps script loaded but Places library not available. Make sure the Places API is enabled in your Google Cloud Console.'));
+          }
+        };
+        
+        checkPlaces();
+      });
+      existingScript.addEventListener('error', () => {
+        reject(new Error('Failed to load Google Maps script'));
+      });
+      return;
+    }
+
+    // Create and load script
+    const script = document.createElement('script');
+    script.src = `https://maps.googleapis.com/maps/api/js?key=${apiKey}&libraries=${libraries}&loading=async`;
+    script.async = true;
+    script.defer = true;
+
+    script.onload = () => {
+      // Wait for the library to initialize with multiple retries
+      let attempts = 0;
+      const maxAttempts = 20; // 2 seconds total (20 * 100ms)
+      
+      const checkPlaces = () => {
+        if (window.google?.maps?.places) {
+          resolve();
+        } else if (attempts < maxAttempts) {
+          attempts++;
+          setTimeout(checkPlaces, 100);
+        } else {
+          // Check if google.maps exists but places doesn't
+          if (window.google?.maps && !window.google.maps.places) {
+            reject(new Error('Google Maps loaded but Places library not available. Make sure the Places API is enabled in your Google Cloud Console and the "places" library is included in the script URL.'));
+          } else if (!window.google) {
+            reject(new Error('Google Maps script loaded but google object not available. Check your API key and network connection.'));
+          } else {
+            reject(new Error('Google Maps script loaded but Places library not available after multiple attempts. Make sure the Places API is enabled in your Google Cloud Console.'));
+          }
+        }
+      };
+      
+      // Start checking immediately, then retry if needed
+      checkPlaces();
+    };
+
+    script.onerror = () => {
+      reject(new Error('Failed to load Google Maps script'));
+    };
+
+    document.head.appendChild(script);
+  });
+}
+
+/**
+ * Check if Google Maps is already loaded
+ */
+export function isGoogleMapsLoaded(): boolean {
+  return !!(window.google && window.google.maps && window.google.maps.places);
+}
+