feat: Resolve zip code to city and state (#119)

Author: yoomlam

frontend/package-lock.json

@@ -42,6 +42,7 @@
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lodash": "^4.17.21",
+    "lru-cache": "^10.4.3",
     "lucide-react": "^0.544.0",
     "next": "^15.1.1",
     "next-intl": "^3.2.1",

frontend/package.json

@@ -7,6 +7,7 @@ import { Button } from "@/components/ui/button";
 import { fetchResources } from "@/util/fetchResources";
 import { Resource } from "@/types/resources";
 import "@/app/globals.css";
+import { fetchLocationFromZip } from "@/util/fetchLocation";
 
 import { PrintableReferralsReport } from "@/util/printReferrals";
 import { fetchActionPlan, ActionPlan } from "@/util/fetchActionPlan";
@@ -48,6 +49,8 @@ export default function Page() {
   const [errorMessage, setErrorMessage] = useState<string | undefined>(
     undefined,
   );
+  const [requestAfterZipResolution, setRequestAfterZipResolution] =
+    useState("");
 
   const searchParams = useSearchParams();
 
@@ -101,14 +104,15 @@ export default function Page() {
     setReadyToPrint(true);
   };
 
-  async function handleClick() {
+  async function findResources() {
     const prompt_version_id = searchParams?.get("prompt_version_id") ?? null;
 
     setLoading(true);
     setResult(null);
     setErrorMessage(undefined);
     try {
-      const request = clientDescription + getCollatedReferralOptions();
+      const request = await buildRequestWithResolvedZipCodes();
+      setRequestAfterZipResolution(request);
       const { resultId, resources, errorMessage } = await fetchResources(
         request,
         userEmail,
@@ -142,6 +146,7 @@ export default function Page() {
     setSelectedResources([]);
     setActionPlan(null);
     setErrorMessage(undefined);
+    setRequestAfterZipResolution("");
   }
 
   function handleResourceSelection(resource: Resource, checked: boolean) {
@@ -187,9 +192,49 @@ export default function Page() {
     }
   }
 
-  const getCollatedReferralOptions = (): string => {
-    const resourceTypeFiltersPrefix =
-      "\nInclude resources that support the following categories: ";
+  const buildRequestWithResolvedZipCodes = async (): Promise<string> => {
+    // Helper function to replace zip codes with "city, state zip_code" format
+    const replaceZipCodes = async (text: string): Promise<string> => {
+      if (!text) return text;
+
+      const zipCodeRegex = /\b\d{5}(?:-\d{4})?\b/g;
+      const matches = Array.from(text.matchAll(zipCodeRegex));
+
+      if (matches.length === 0) return text;
+
+      // Collect unique zip codes to avoid duplicate API calls
+      const uniqueZipCodes = Array.from(new Set(matches.map((m) => m[0])));
+
+      // Fetch locations for all unique zip codes
+      const zipToLocation = new Map<string, string>();
+      const locationPromises = uniqueZipCodes.map(async (zipCode) => {
+        // For zip+4 format, only use the 5-digit part for lookup
+        const zipForLookup = zipCode.split("-")[0];
+        const location = await fetchLocationFromZip(zipForLookup);
+        zipToLocation.set(zipCode, location);
+      });
+      await Promise.all(locationPromises);
+
+      // Replace all zip codes with their city, state prepended
+      let result = text;
+      for (const [zipCode, location] of zipToLocation.entries()) {
+        if (location) {
+          // Use a global replace to handle all occurrences of this zip code
+          const zipRegex = new RegExp(
+            `\\b${zipCode.replace(/-/g, "\\-")}\\b`,
+            "g",
+          );
+          result = result.replace(zipRegex, `${location} ${zipCode}`);
+        }
+      }
+
+      return result;
+    };
+
+    // Process both locationText and clientDescription for zip codes
+    const processedLocationText = await replaceZipCodes(locationText);
+    const processedClientDescription = await replaceZipCodes(clientDescription);
+
     const resourceTypeFilters = selectedCategories
       .map((categoryId) => {
         const category = resourceCategories.find((c) => c.id === categoryId);
@@ -198,22 +243,21 @@ export default function Page() {
       .filter(Boolean)
       .join(", ");
 
-    const providerTypeFiltersPrefix =
-      "\nInclude the following types of providers: ";
-    const providerTypeFilters = selectedResourceTypes.join(", ");
-
-    const locationFilterPrefix =
-      "\nFocus on resources close to the following location: ";
-
-    return (
+    const options =
       (resourceTypeFilters.length > 0
-        ? resourceTypeFiltersPrefix + resourceTypeFilters
+        ? "\nInclude resources that support the following categories: " +
+          resourceTypeFilters
         : "") +
-      (providerTypeFilters
-        ? providerTypeFiltersPrefix + providerTypeFilters
+      (selectedResourceTypes.length > 0
+        ? "\nInclude the following types of providers: " +
+          selectedResourceTypes.join(", ")
         : "") +
-      (locationText.length > 0 ? locationFilterPrefix + locationText : "")
-    );
+      (processedLocationText.length > 0
+        ? "\nFocus on resources close to the following location: " +
+          processedLocationText
+        : "");
+
+    return processedClientDescription + options;
   };
 
   // Show nothing while checking localStorage to prevent flash
@@ -331,7 +375,7 @@ export default function Page() {
                     onToggleResourceType={toggleResourceType}
                     onLocationChange={setLocationText}
                     onClientDescriptionChange={setClientDescription}
-                    onFindResources={() => void handleClick()}
+                    onFindResources={() => void findResources()}
                   />
                 )}
               </TabsContent>
@@ -373,29 +417,36 @@ export default function Page() {
                     {resultId && <EmailReferralsButton resultId={resultId} />}
                   </div>
                 </div>
-                <ClientDetailsPromptBubble
-                  clientDescription={
-                    clientDescription + getCollatedReferralOptions()
-                  }
-                />
-                <ResourcesList
-                  resources={retainedResources ?? []}
-                  errorMessage={errorMessage}
-                  handleRemoveResource={handleRemoveResource}
-                />
-                {retainedResources && retainedResources.length > 0 && (
-                  <ActionPlanSection
-                    resources={retainedResources}
-                    selectedResources={selectedResources}
-                    actionPlan={actionPlan}
-                    isGeneratingActionPlan={isGeneratingActionPlan}
-                    onResourceSelection={handleResourceSelection}
-                    onSelectAllResources={handleSelectAllResources}
-                    onGenerateActionPlan={() => void generateActionPlan()}
-                  />
-                )}
               </div>
             )}
+
+            {requestAfterZipResolution && (
+              <ClientDetailsPromptBubble
+                clientDescription={requestAfterZipResolution}
+              />
+            )}
+
+            {readyToPrint && (
+              <ResourcesList
+                resources={retainedResources ?? []}
+                errorMessage={errorMessage}
+                handleRemoveResource={handleRemoveResource}
+              />
+            )}
+
+            {readyToPrint &&
+              retainedResources &&
+              retainedResources.length > 0 && (
+                <ActionPlanSection
+                  resources={retainedResources}
+                  selectedResources={selectedResources}
+                  actionPlan={actionPlan}
+                  isGeneratingActionPlan={isGeneratingActionPlan}
+                  onResourceSelection={handleResourceSelection}
+                  onSelectAllResources={handleSelectAllResources}
+                  onGenerateActionPlan={() => void generateActionPlan()}
+                />
+              )}
           </div>
         </div>
       )}

frontend/src/app/[locale]/generate-referrals/page.tsx

@@ -146,6 +146,7 @@ export function ClientDetailsInput({
                     onClick={() => onToggleCategory(category.id)}
                     data-testid={"resourceCategoryToggle-" + category.id}
                     aria-pressed={isSelected}
+                    disabled={loading}
                   >
                     <Icon className="mr-2 w-6 h-6" />
                     {category.label}
@@ -176,6 +177,7 @@ export function ClientDetailsInput({
                 onClick={() => onToggleResourceType("goodwill")}
                 data-testid={"resourceCategoryToggle-goodwill"}
                 aria-pressed={selectedResourceTypes.includes("goodwill")}
+                disabled={loading}
               >
                 <Heart className="w-4 h-4 mr-2" />
                 Goodwill Internal
@@ -195,6 +197,7 @@ export function ClientDetailsInput({
                 onClick={() => onToggleResourceType("government")}
                 data-testid={"resourceCategoryToggle-government"}
                 aria-pressed={selectedResourceTypes.includes("government")}
+                disabled={loading}
               >
                 <Building className="w-4 h-4 mr-2" />
                 Government
@@ -214,6 +217,7 @@ export function ClientDetailsInput({
                 onClick={() => onToggleResourceType("community")}
                 data-testid={"resourceCategoryToggle-community"}
                 aria-pressed={selectedResourceTypes.includes("community")}
+                disabled={loading}
               >
                 <Users className="w-4 h-4 mr-2" />
                 Community
@@ -234,6 +238,7 @@ export function ClientDetailsInput({
                 onChange={(e) => onLocationChange(e.target.value)}
                 className="border-gray-300 bg-white focus:ring-blue-500 focus:border-blue-500"
                 data-testid="locationFilterInput"
+                disabled={loading}
               />
             </div>
           </div>
@@ -249,6 +254,7 @@ export function ClientDetailsInput({
                 onClick={onClearAllFilters}
                 className="text-gray-700 hover:bg-gray-100 hover:text-gray-900"
                 data-testid="clearFiltersButton"
+                disabled={loading}
               >
                 Clear All Filters
               </Button>
@@ -270,6 +276,7 @@ export function ClientDetailsInput({
           onChange={(e) => onClientDescriptionChange(e.target.value)}
           className="min-h-[8rem] min-w-[16rem] text-base"
           data-testid="clientDescriptionInput"
+          disabled={loading}
         />
       </div>
 

frontend/src/components/ClientDetailsInput.tsx

@@ -0,0 +1,62 @@
+import { LRUCache } from "lru-cache";
+
+interface ZippopotamPlace {
+  "place name": string; // city name
+  state: string;
+  "state abbreviation": string;
+  longitude: string;
+  latitude: string;
+}
+
+interface ZippopotamResponse {
+  places?: ZippopotamPlace[];
+}
+
+// Cache for storing zip code lookup results (max 100 entries)
+const zipCodeCache = new LRUCache<string, string>({
+  max: 100,
+});
+
+export async function fetchLocationFromZip(zipCode: string): Promise<string> {
+  // Check cache first
+  const cachedValue = zipCodeCache.get(zipCode);
+  if (cachedValue !== undefined) {
+    return cachedValue;
+  }
+
+  const ac = new AbortController();
+  const timeoutId = setTimeout(() => ac.abort(), 5_000);
+
+  try {
+    const response = await fetch(`https://api.zippopotam.us/us/${zipCode}`, {
+      signal: ac.signal,
+    });
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      // Cache empty string for failed lookups
+      zipCodeCache.set(zipCode, "");
+      return "";
+    }
+
+    const data = (await response.json()) as ZippopotamResponse;
+    const place = data.places?.[0];
+    if (place) {
+      const result = `${place["place name"]}, ${place["state abbreviation"]}`;
+      // Cache successful result
+      zipCodeCache.set(zipCode, result);
+      return result;
+    }
+  } catch (error) {
+    clearTimeout(timeoutId);
+    if (error instanceof Error && error.name === "AbortError") {
+      console.warn("Zip code lookup timed out:", zipCode);
+    } else {
+      console.warn("Error fetching city/state from zip code:", error);
+    }
+  }
+
+  // Cache empty string if no place found or errors (including timeouts)
+  zipCodeCache.set(zipCode, "");
+  return "";
+}

frontend/src/util/fetchLocation.ts

@@ -258,7 +258,7 @@ describe("Generate Referrals Page", () => {
     });
   });
 
-  describe("handleClick", () => {
+  describe("findResources", () => {
     it("calls fetchResources with client description and filters", async () => {
       const user = userEvent.setup();
       const fetchResourcesSpy = jest