@jmruthers/pace-core 0.6.9 → 0.6.11

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

@@ -16,6 +16,7 @@
  */
 
 import { getOrCreateRequest } from '../request-deduplication';
+import { ok, err, type ApiResult, type ApiError } from '../../types/api-result';
 import { createLogger } from '../core/logger';
 import { loadGoogleMapsScript, isGoogleMapsLoaded } from './loadGoogleMapsScript';
 import type {
@@ -26,6 +27,14 @@ import type {
 
 const log = createLogger('google-places');
 
+function toApiError(error: unknown): ApiError {
+  const message = error instanceof Error ? error.message : 'Unknown error';
+  const code = error instanceof Error && (error as Error & { code?: string }).code
+    ? (error as Error & { code: string }).code
+    : 'GOOGLE_PLACES_ERROR';
+  return { code, message };
+}
+
 // Google Maps types are defined in loadGoogleMapsScript.ts
 
 /**
@@ -34,33 +43,36 @@ const log = createLogger('google-places');
  * @param query - Search query string
  * @param apiKey - Google Places API key
  * @param options - Optional autocomplete options
- * @returns Promise resolving to array of predictions
+ * @returns Promise resolving to ApiResult with array of predictions
  *
  * @example
  * ```ts
- * const predictions = await fetchPlaceAutocomplete(
+ * const result = await fetchPlaceAutocomplete(
  *   '123 Main St',
  *   'your-api-key',
  *   { components: 'country:au' }
  * );
+ * if (result.ok) console.log(result.data);
  * ```
  */
 export async function fetchPlaceAutocomplete(
   query: string,
   apiKey: string,
   options?: AutocompleteOptions
-): Promise<GooglePlaceAutocompletePrediction[]> {
+): Promise<ApiResult<GooglePlaceAutocompletePrediction[]>> {
   if (!query.trim()) {
-    return [];
+    return ok([]);
   }
 
   if (!apiKey) {
-    throw new Error('Google Places API key is required');
+    return err({ code: 'VALIDATION_ERROR', message: 'Google Places API key is required' });
   }
 
-  // Ensure Google Maps script is loaded
   if (!isGoogleMapsLoaded()) {
-    await loadGoogleMapsScript(apiKey, 'places');
+    const loadResult = await loadGoogleMapsScript(apiKey, 'places');
+    if (!loadResult.ok) {
+      return err(loadResult.error);
+    }
   }
 
   const requestKey = `google-places-autocomplete:${query}:${JSON.stringify(options || {})}`;
@@ -125,11 +137,11 @@ export async function fetchPlaceAutocomplete(
         }
 
         // Call new API
-        return new Promise<GooglePlaceAutocompletePrediction[]>((resolve, reject) => {
+        return new Promise<ApiResult<GooglePlaceAutocompletePrediction[]>>((resolve) => {
           window.google!.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request)
             .then((response) => {
               if (response.suggestions && response.suggestions.length > 0) {
-                const result: GooglePlaceAutocompletePrediction[] = response.suggestions
+                const data: GooglePlaceAutocompletePrediction[] = response.suggestions
                   .filter(s => s.placePrediction)
                   .map((s) => ({
                     description: s.placePrediction!.text.text,
@@ -139,16 +151,16 @@ export async function fetchPlaceAutocomplete(
                       secondary_text: s.placePrediction!.structuredFormat?.secondaryText?.text || '',
                     },
                   }));
-                log.debug(`Received ${result.length} predictions (new API)`);
-                resolve(result);
+                log.debug(`Received ${data.length} predictions (new API)`);
+                resolve(ok(data));
               } else {
                 log.debug('No results found (new API)');
-                resolve([]);
+                resolve(ok([]));
               }
             })
             .catch((error) => {
               log.error('Autocomplete fetch failed (new API):', error);
-              reject(new Error(`Failed to fetch autocomplete predictions: ${error.message || 'Unknown error'}`));
+              resolve(err({ code: 'AUTOCOMPLETE_ERROR', message: error.message || 'Unknown error' }));
             });
         });
       }
@@ -171,7 +183,6 @@ export async function fetchPlaceAutocomplete(
       // 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) => {
@@ -207,12 +218,11 @@ export async function fetchPlaceAutocomplete(
       }
 
       // Call AutocompleteService
-      return new Promise<GooglePlaceAutocompletePrediction[]>((resolve, reject) => {
+      return new Promise<ApiResult<GooglePlaceAutocompletePrediction[]>>((resolve) => {
         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) => ({
+            const data: GooglePlaceAutocompletePrediction[] = predictions.map((pred) => ({
               description: pred.description,
               place_id: pred.place_id,
               structured_formatting: {
@@ -220,44 +230,26 @@ export async function fetchPlaceAutocomplete(
                 secondary_text: pred.structured_formatting.secondary_text,
               },
             }));
-            resolve(result);
+            resolve(ok(data));
           } else if (status === 'ZERO_RESULTS') {
             log.debug('No results found');
-            resolve([]);
+            resolve(ok([]));
           } else {
             const errorMsg = `Google Places API error: ${status}`;
             log.error('Autocomplete fetch failed:', errorMsg);
-            reject(new Error(errorMsg));
+            resolve(err({ code: 'AUTOCOMPLETE_ERROR', message: 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');
+    } catch (e) {
+      log.error('Autocomplete fetch failed:', e);
+      return err(toApiError(e));
     }
   });
 }
 
-/**
- * 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 details shape from Google Places API */
+type PlaceDetails = {
   place_id: string;
   formatted_address?: string;
   address_components?: Array<{
@@ -271,18 +263,29 @@ export async function fetchPlaceDetails(
       lng: () => number;
     };
   };
-}> {
+};
+
+/**
+ * Fetch place details from Google Places API.
+ * @returns Promise resolving to ApiResult with place details
+ */
+export async function fetchPlaceDetails(
+  placeId: string,
+  apiKey: string
+): Promise<ApiResult<PlaceDetails>> {
   if (!placeId) {
-    throw new Error('Place ID is required');
+    return err({ code: 'VALIDATION_ERROR', message: 'Place ID is required' });
   }
 
   if (!apiKey) {
-    throw new Error('Google Places API key is required');
+    return err({ code: 'VALIDATION_ERROR', message: 'Google Places API key is required' });
   }
 
-  // Ensure Google Maps script is loaded
   if (!isGoogleMapsLoaded()) {
-    await loadGoogleMapsScript(apiKey, 'places');
+    const loadResult = await loadGoogleMapsScript(apiKey, 'places');
+    if (!loadResult.ok) {
+      return err(loadResult.error);
+    }
   }
 
   const requestKey = `google-places-details:${placeId}`;
@@ -292,29 +295,13 @@ export async function fetchPlaceDetails(
       log.debug(`Fetching place details for place_id: ${placeId}`);
 
       if (!window.google?.maps?.places) {
-        throw new Error('Google Maps Places library not available');
+        return err({ code: 'PLACES_UNAVAILABLE', message: '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) => {
+      return new Promise<ApiResult<PlaceDetails>>((resolve) => {
         placesService.getDetails(
           {
             placeId: placeId,
@@ -323,25 +310,21 @@ export async function fetchPlaceDetails(
           (place, status) => {
             if (status === 'OK' && place) {
               log.debug('Place details fetched successfully');
-              resolve(place as any);
+              resolve(ok(place as PlaceDetails));
             } else if (status === 'NOT_FOUND') {
               log.error('Place not found:', placeId);
-              reject(new Error('Place not found'));
+              resolve(err({ code: 'NOT_FOUND', message: 'Place not found' }));
             } else {
               const errorMsg = `Failed to fetch place details: ${status}`;
               log.error('Place details fetch failed:', errorMsg);
-              reject(new Error(errorMsg));
+              resolve(err({ code: 'PLACE_DETAILS_ERROR', message: 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');
+    } catch (e) {
+      log.error('Place details fetch failed:', e);
+      return err(toApiError(e));
     }
   });
 }
@@ -452,24 +435,22 @@ export function createAddressFromPlaceResult(
  *
  * @param placeId - Google Place ID
  * @param apiKey - Google Places API key
- * @returns Promise resolving to parsed address
+ * @returns Promise resolving to ApiResult with parsed address
  *
  * @example
  * ```ts
- * const address = await getAddressByPlaceId('ChIJ...', 'your-api-key');
- * // Returns: { place_id: 'ChIJ...', full_address: '...', ... }
+ * const result = await getAddressByPlaceId('ChIJ...', 'your-api-key');
+ * if (result.ok) console.log(result.data);
  * ```
  */
 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;
+): Promise<ApiResult<ParsedAddress | null>> {
+  const placeResult = await fetchPlaceDetails(placeId, apiKey);
+  if (!placeResult.ok) {
+    return placeResult;
   }
+  return ok(createAddressFromPlaceResult(placeResult.data));
 }
 

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

@@ -1,7 +1,7 @@
 /**
  * @file Google Maps Script Loader Tests
  * @package @jmruthers/pace-core
- * @module Utils/GooglePlaces/__tests__
+ * @module Utils/GooglePlaces
  * @since 0.1.0
  */
 
@@ -33,8 +33,9 @@ describe('loadGoogleMapsScript', () => {
     (window as any).google = { maps: { places: {} } };
     const appendSpy = vi.spyOn(document.head, 'appendChild');
 
-    await expect(loadGoogleMapsScript('ready-key')).resolves.toBeUndefined();
-
+    const result = await loadGoogleMapsScript('ready-key');
+    expect(result.ok).toBe(true);
+    expect(result.data).toBeUndefined();
     expect(appendSpy).not.toHaveBeenCalled();
   });
 
@@ -50,7 +51,8 @@ describe('loadGoogleMapsScript', () => {
     (window as any).google = { maps: { places: {} } };
     scriptEl.onload?.(new Event('load'));
 
-    await expect(loadPromise).resolves.toBeUndefined();
+    const result = await loadPromise;
+    expect(result.ok).toBe(true);
   });
 
   it('reuses an existing script element', async () => {
@@ -65,11 +67,12 @@ describe('loadGoogleMapsScript', () => {
     (window as any).google = { maps: { places: {} } };
     existingScript.dispatchEvent(new Event('load'));
 
-    await expect(loadPromise).resolves.toBeUndefined();
+    const result = await loadPromise;
+    expect(result.ok).toBe(true);
     expect(appendSpy).not.toHaveBeenCalled();
   });
 
-  it('rejects when the script fails to load', async () => {
+  it('returns err when the script fails to load', async () => {
     const appendSpy = vi.spyOn(document.head, 'appendChild');
 
     const loadPromise = loadGoogleMapsScript('bad-key');
@@ -77,7 +80,64 @@ describe('loadGoogleMapsScript', () => {
 
     scriptEl.onerror?.(new Event('error'));
 
-    await expect(loadPromise).rejects.toThrow('Failed to load Google Maps script');
+    const result = await loadPromise;
+    expect(result.ok).toBe(false);
+    expect(result.error.message).toContain('Failed to load Google Maps script');
   });
-});
 
+  it('returns err when an existing script never exposes Places', async () => {
+    vi.useFakeTimers();
+
+    const existingScript = document.createElement('script');
+    existingScript.src = 'https://maps.googleapis.com/maps/api/js?key=existing&libraries=places&loading=async';
+    existingScript.setAttribute('data-loaded', 'true');
+    document.head.appendChild(existingScript);
+
+    const loadPromise = loadGoogleMapsScript('new-key');
+
+    await vi.runAllTimersAsync();
+
+    const result = await loadPromise;
+    expect(result.ok).toBe(false);
+    expect(result.error.message).toContain('Places library not available');
+
+    vi.useRealTimers();
+  });
+
+  it('returns err when maps loads without the Places library', async () => {
+    vi.useFakeTimers();
+
+    const appendSpy = vi.spyOn(document.head, 'appendChild');
+    const loadPromise = loadGoogleMapsScript('api-key');
+    const scriptEl = appendSpy.mock.calls[0][0] as HTMLScriptElement;
+
+    (window as any).google = { maps: {} };
+    scriptEl.onload?.(new Event('load'));
+
+    await vi.runAllTimersAsync();
+
+    const result = await loadPromise;
+    expect(result.ok).toBe(false);
+    expect(result.error.message).toContain('Places library not available');
+
+    vi.useRealTimers();
+  });
+
+  it('returns err when google is not available after the script loads', async () => {
+    vi.useFakeTimers();
+
+    const appendSpy = vi.spyOn(document.head, 'appendChild');
+    const loadPromise = loadGoogleMapsScript('api-key');
+    const scriptEl = appendSpy.mock.calls[0][0] as HTMLScriptElement;
+
+    scriptEl.onload?.(new Event('load'));
+
+    await vi.runAllTimersAsync();
+
+    const result = await loadPromise;
+    expect(result.ok).toBe(false);
+    expect(result.error.message).toContain('google object not available');
+
+    vi.useRealTimers();
+  });
+});