@callforge/tracking-client 0.7.0 → 0.7.1

package/README.md

@@ -43,7 +43,13 @@ const client = CallForge.init({
 const { session, location } = client.getSessionAsync();
 
 // Location is delivered independently (often faster than phone number assignment)
-console.log(await location); // { city: "Woodstock", state: "Georgia", stateCode: "GA" } or null
+console.log(await location);
+// {
+//   city: "Woodstock",
+//   state: "Georgia",
+//   stateCode: "GA",
+//   zipOptions: ["30188", "30189", "30066", ...] // may be []
+// } or null
 
 // Phone session data (deterministic token + phone number)
 console.log(await session);  // { sessionToken, leaseId, phoneNumber }
@@ -160,7 +166,16 @@ Get location data only. Returns cached data if valid, otherwise fetches from the
 
 ```typescript
 const location = await client.getLocation();
-// { city, state, stateCode } or null
+// { city, state, stateCode, zipOptions } or null
+```
+
+```typescript
+interface TrackingLocation {
+  city: string;
+  state: string;
+  stateCode: string;
+  zipOptions?: string[]; // ordered by proximity, may be []
+}
 ```
 
 ### `client.getSessionAsync()`
@@ -172,6 +187,7 @@ const { session, location } = client.getSessionAsync();
 
 location.then((loc) => {
   // show city/state ASAP
+  // optionally render loc?.zipOptions in a ZIP picker
 });
 
 session.then((sess) => {
@@ -204,7 +220,7 @@ Subscribe to location ready event. Callback is called once location data is avai
 
 ```typescript
 client.onLocationReady((location) => {
-  // location is { city, state, stateCode } or null
+  // location is { city, state, stateCode, zipOptions } or null
 });
 ```
 

package/dist/index.d.mts

@@ -21,6 +21,8 @@ interface TrackingLocation {
     state: string;
     /** State abbreviation (e.g., "GA") */
     stateCode: string;
+    /** Suggested ZIPs ordered by proximity (may be empty) */
+    zipOptions?: string[];
 }
 type TrackingLocationSource = 'google_criteria' | 'cloudflare_geo';
 /**
@@ -70,6 +72,7 @@ interface ApiLocationResponse {
         stateCode: string;
         source: TrackingLocationSource;
     } | null;
+    zipOptions?: string[];
     expiresAt: number;
 }
 interface CallIntentResponse {
@@ -174,6 +177,8 @@ declare class CallForge {
     private fetchLocationFromApi;
     private saveToCache;
     private saveLocationToCache;
+    private toTrackingLocation;
+    private normalizeZipOptions;
     private formatSession;
     private formatApiResponse;
     private syncParamsToCallForgeIfPossible;

package/dist/index.d.ts

@@ -21,6 +21,8 @@ interface TrackingLocation {
     state: string;
     /** State abbreviation (e.g., "GA") */
     stateCode: string;
+    /** Suggested ZIPs ordered by proximity (may be empty) */
+    zipOptions?: string[];
 }
 type TrackingLocationSource = 'google_criteria' | 'cloudflare_geo';
 /**
@@ -70,6 +72,7 @@ interface ApiLocationResponse {
         stateCode: string;
         source: TrackingLocationSource;
     } | null;
+    zipOptions?: string[];
     expiresAt: number;
 }
 interface CallIntentResponse {
@@ -174,6 +177,8 @@ declare class CallForge {
     private fetchLocationFromApi;
     private saveToCache;
     private saveLocationToCache;
+    private toTrackingLocation;
+    private normalizeZipOptions;
     private formatSession;
     private formatApiResponse;
     private syncParamsToCallForgeIfPossible;

package/dist/index.js

@@ -424,18 +424,14 @@ var CallForge = class _CallForge {
     return this.formatApiResponse(data);
   }
   async fetchLocation() {
-    var _a;
+    var _a, _b;
     const locationId = this.getLocationId();
     if (typeof window !== "undefined" && window.__cfTrackingLocation) {
       try {
         const data2 = await window.__cfTrackingLocation;
         const dataWithExtras = data2;
         const effectiveLocId = (_a = dataWithExtras.locId) != null ? _a : locationId;
-        const location2 = data2.location ? {
-          city: data2.location.city,
-          state: data2.location.state,
-          stateCode: data2.location.stateCode
-        } : null;
+        const location2 = this.toTrackingLocation(data2.location, dataWithExtras.zipOptions);
         this.saveLocationToCache(effectiveLocId, location2, data2.expiresAt);
         return location2;
       } catch (e) {
@@ -443,14 +439,10 @@ var CallForge = class _CallForge {
     }
     const cached = this.locationCache.get(locationId);
     if (cached) {
-      return cached.location;
+      return this.toTrackingLocation(cached.location, (_b = cached.location) == null ? void 0 : _b.zipOptions);
     }
     const data = await this.fetchLocationFromApi(locationId);
-    const location = data.location ? {
-      city: data.location.city,
-      state: data.location.state,
-      stateCode: data.location.stateCode
-    } : null;
+    const location = this.toTrackingLocation(data.location, data.zipOptions);
     this.saveLocationToCache(locationId, location, data.expiresAt);
     return location;
   }
@@ -525,6 +517,27 @@ var CallForge = class _CallForge {
       tokenVersion: "v1"
     });
   }
+  toTrackingLocation(location, zipOptions) {
+    if (!location) {
+      return null;
+    }
+    return {
+      city: location.city,
+      state: location.state,
+      stateCode: location.stateCode,
+      zipOptions: this.normalizeZipOptions(zipOptions)
+    };
+  }
+  normalizeZipOptions(value) {
+    if (!Array.isArray(value)) {
+      return [];
+    }
+    return Array.from(
+      new Set(
+        value.filter((zip) => typeof zip === "string" && /^\d{5}$/.test(zip))
+      )
+    );
+  }
   formatSession(cached) {
     return {
       sessionToken: cached.sessionToken,
@@ -609,12 +622,12 @@ var lkey='cf_location_v1_'+site;
 try{
 var cl=JSON.parse(localStorage.getItem(lkey));
 if(cl&&cl.expiresAt>Date.now()+30000){
-if(!loc||(loc&&cl.locId===loc)){window.__cfTrackingLocation=Promise.resolve(cl)}
+if(!loc||(loc&&cl.locId===loc)){if(cl.location&&!Array.isArray(cl.location.zipOptions))cl.location.zipOptions=[];window.__cfTrackingLocation=Promise.resolve(cl)}
 }}catch(e){}
 if(!window.__cfTrackingLocation){
 var lurl='${endpoint}/v1/tracking/location';
 if(loc)lurl+='?loc_physical_ms='+encodeURIComponent(loc);
-window.__cfTrackingLocation=fetch(lurl,{credentials:'omit'}).then(function(r){if(!r.ok)throw new Error('tracking preload location failed');return r.json()}).then(function(d){d.locId=loc;try{localStorage.setItem(lkey,JSON.stringify({locId:loc,location:d.location?{city:d.location.city,state:d.location.state,stateCode:d.location.stateCode}:null,expiresAt:d.expiresAt,tokenVersion:'v1'}))}catch(e){}return d});
+window.__cfTrackingLocation=fetch(lurl,{credentials:'omit'}).then(function(r){if(!r.ok)throw new Error('tracking preload location failed');return r.json()}).then(function(d){var z=Array.isArray(d.zipOptions)?d.zipOptions.filter(function(x){return /^\\d{5}$/.test(x)}):[];d.locId=loc;d.zipOptions=z;try{localStorage.setItem(lkey,JSON.stringify({locId:loc,location:d.location?{city:d.location.city,state:d.location.state,stateCode:d.location.stateCode,zipOptions:z}:null,expiresAt:d.expiresAt,tokenVersion:'v1'}))}catch(e){}return d});
 }
 var token=null;
 try{

package/dist/index.mjs

@@ -400,18 +400,14 @@ var CallForge = class _CallForge {
     return this.formatApiResponse(data);
   }
   async fetchLocation() {
-    var _a;
+    var _a, _b;
     const locationId = this.getLocationId();
     if (typeof window !== "undefined" && window.__cfTrackingLocation) {
       try {
         const data2 = await window.__cfTrackingLocation;
         const dataWithExtras = data2;
         const effectiveLocId = (_a = dataWithExtras.locId) != null ? _a : locationId;
-        const location2 = data2.location ? {
-          city: data2.location.city,
-          state: data2.location.state,
-          stateCode: data2.location.stateCode
-        } : null;
+        const location2 = this.toTrackingLocation(data2.location, dataWithExtras.zipOptions);
         this.saveLocationToCache(effectiveLocId, location2, data2.expiresAt);
         return location2;
       } catch (e) {
@@ -419,14 +415,10 @@ var CallForge = class _CallForge {
     }
     const cached = this.locationCache.get(locationId);
     if (cached) {
-      return cached.location;
+      return this.toTrackingLocation(cached.location, (_b = cached.location) == null ? void 0 : _b.zipOptions);
     }
     const data = await this.fetchLocationFromApi(locationId);
-    const location = data.location ? {
-      city: data.location.city,
-      state: data.location.state,
-      stateCode: data.location.stateCode
-    } : null;
+    const location = this.toTrackingLocation(data.location, data.zipOptions);
     this.saveLocationToCache(locationId, location, data.expiresAt);
     return location;
   }
@@ -501,6 +493,27 @@ var CallForge = class _CallForge {
       tokenVersion: "v1"
     });
   }
+  toTrackingLocation(location, zipOptions) {
+    if (!location) {
+      return null;
+    }
+    return {
+      city: location.city,
+      state: location.state,
+      stateCode: location.stateCode,
+      zipOptions: this.normalizeZipOptions(zipOptions)
+    };
+  }
+  normalizeZipOptions(value) {
+    if (!Array.isArray(value)) {
+      return [];
+    }
+    return Array.from(
+      new Set(
+        value.filter((zip) => typeof zip === "string" && /^\d{5}$/.test(zip))
+      )
+    );
+  }
   formatSession(cached) {
     return {
       sessionToken: cached.sessionToken,
@@ -585,12 +598,12 @@ var lkey='cf_location_v1_'+site;
 try{
 var cl=JSON.parse(localStorage.getItem(lkey));
 if(cl&&cl.expiresAt>Date.now()+30000){
-if(!loc||(loc&&cl.locId===loc)){window.__cfTrackingLocation=Promise.resolve(cl)}
+if(!loc||(loc&&cl.locId===loc)){if(cl.location&&!Array.isArray(cl.location.zipOptions))cl.location.zipOptions=[];window.__cfTrackingLocation=Promise.resolve(cl)}
 }}catch(e){}
 if(!window.__cfTrackingLocation){
 var lurl='${endpoint}/v1/tracking/location';
 if(loc)lurl+='?loc_physical_ms='+encodeURIComponent(loc);
-window.__cfTrackingLocation=fetch(lurl,{credentials:'omit'}).then(function(r){if(!r.ok)throw new Error('tracking preload location failed');return r.json()}).then(function(d){d.locId=loc;try{localStorage.setItem(lkey,JSON.stringify({locId:loc,location:d.location?{city:d.location.city,state:d.location.state,stateCode:d.location.stateCode}:null,expiresAt:d.expiresAt,tokenVersion:'v1'}))}catch(e){}return d});
+window.__cfTrackingLocation=fetch(lurl,{credentials:'omit'}).then(function(r){if(!r.ok)throw new Error('tracking preload location failed');return r.json()}).then(function(d){var z=Array.isArray(d.zipOptions)?d.zipOptions.filter(function(x){return /^\\d{5}$/.test(x)}):[];d.locId=loc;d.zipOptions=z;try{localStorage.setItem(lkey,JSON.stringify({locId:loc,location:d.location?{city:d.location.city,state:d.location.state,stateCode:d.location.stateCode,zipOptions:z}:null,expiresAt:d.expiresAt,tokenVersion:'v1'}))}catch(e){}return d});
 }
 var token=null;
 try{

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callforge/tracking-client",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -17,17 +17,17 @@
   "files": [
     "dist"
   ],
-  "devDependencies": {
-    "jsdom": "^27.4.0",
-    "tsup": "^8.0.0",
-    "typescript": "^5.3.0",
-    "vitest": "^1.6.0",
-    "@callforge/tsconfig": "0.0.0"
-  },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts",
     "clean": "rm -rf dist",
     "test": "vitest run",
     "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@callforge/tsconfig": "workspace:*",
+    "jsdom": "^27.4.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^1.6.0"
   }
-}
+}