workAreaAddressSearch.ts

Purpose

This module provides a two-step address resolution flow backed by the Google Places Autocomplete and Place Details APIs. It is used by location.ts to convert a user-entered address string into geographic coordinates for work area setup.

Its responsibilities include:

• Resolving the Google Places API key from environment variables or Expo config
• Building correctly encoded query URLs for both API endpoints
• Fetching autocomplete predictions for a partial address input
• Resolving a selected autocomplete suggestion to full coordinates via Place Details
• Filtering and normalizing API responses into typed application models
• Surfacing descriptive errors for API failures, missing keys, and missing results

Invariants

Minimum Input Length

searchWorkAreaAddressSuggestions returns an empty array immediately when the trimmed input is fewer than 3 characters.

No API call is made for very short inputs.

API Key Requirement

Both searchWorkAreaAddressSuggestions and resolveWorkAreaAddressSuggestion throw Error("Google Places API key is not configured.") if no key is available.

API Key Resolution Order

The API key is resolved from the first available source in this priority order:

1. process.env.EXPO_PUBLIC_GOOGLE_PLACES_API_KEY
2. process.env.YOUR_GOOGLE_MAPS_API_KEY
3. Constants.expoConfig?.extra?.googlePlacesApiKey

An empty string at any level is treated as absent.

Session Token Scope

A session token must be passed by the caller to both searchWorkAreaAddressSuggestions and resolveWorkAreaAddressSuggestion.

Billing for autocomplete + details within the same session is grouped by Google when the same token is used for both calls. Token generation is the caller’s responsibility.

Coordinate Presence Validation

resolveWorkAreaAddressSuggestion throws if the Place Details response does not include numeric lat and lng values in geometry.location.

This prevents returning a partial result that would silently fail downstream.

Prediction Filtering

Autocomplete predictions are filtered to only those with a place_id and a description before being mapped to WorkAreaAddressSuggestion.

Predictions missing either field are silently dropped.

Exports

WorkAreaAddressSuggestion

type WorkAreaAddressSuggestion = {
	placeId: string;
	description: string;
	mainText: string;
	secondaryText: string;
};

WorkAreaResolvedAddress

type WorkAreaResolvedAddress = {
	description: string;
	centerLat: number;
	centerLon: number;
};

getGooglePlacesApiKey()

function getGooglePlacesApiKey(): string | null

Returns the configured Google Places API key, or null if none is available.

searchWorkAreaAddressSuggestions(...)

async function searchWorkAreaAddressSuggestions(
	input: string,
	sessionToken: string,
): Promise<WorkAreaAddressSuggestion[]>

Returns autocomplete suggestions for the given input. Returns an empty array for inputs shorter than 3 characters or with zero API results. Throws on API errors or missing key.

resolveWorkAreaAddressSuggestion(...)

async function resolveWorkAreaAddressSuggestion(
	suggestion: WorkAreaAddressSuggestion,
	sessionToken: string,
): Promise<WorkAreaResolvedAddress>

Resolves a selected autocomplete suggestion to full address text and coordinates. Throws if coordinates are absent in the API response or the request fails.