@callforge/tracking-client 0.6.3 → 0.7.1

package/README.md

@@ -30,7 +30,7 @@ Generated HTML:
 <script>/* preload script */</script>
 ```
 
-### 2. Initialize and fetch a tracking session
+### 2. Initialize and start session + location requests
 
 ```typescript
 import { CallForge } from '@callforge/tracking-client';
@@ -40,9 +40,19 @@ const client = CallForge.init({
   // endpoint: 'https://tracking-dev.callforge.io', // Optional: override for dev
 });
 
-const session = await client.getSession();
-console.log(session.phoneNumber);  // "+17705550000" or null
-console.log(session.location);     // { city: "Woodstock", state: "Georgia", stateCode: "GA" } or null
+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",
+//   zipOptions: ["30188", "30189", "30066", ...] // may be []
+// } or null
+
+// Phone session data (deterministic token + phone number)
+console.log(await session);  // { sessionToken, leaseId, phoneNumber }
 ```
 
 ### 3. Deterministic click/callback attribution (optional)
@@ -134,18 +144,13 @@ interface CallForgeConfig {
 
 ### `client.getSession()`
 
-Get tracking session data. Returns cached data if valid, otherwise fetches from the API.
+Get tracking session data (phone number + deterministic session token). Returns cached data if valid, otherwise fetches from the API.
 
 ```typescript
 interface TrackingSession {
   sessionToken: string;      // Signed, opaque token used to refresh the session
   leaseId: string | null;    // Deterministic assignment lease ID (when available)
   phoneNumber: string | null;
-  location: {
-    city: string;
-    state: string;      // Full name: "Georgia"
-    stateCode: string;  // Abbreviation: "GA"
-  } | null;
 }
 ```
 
@@ -155,6 +160,41 @@ Behavior:
 - If `loc_physical_ms` is present in the URL, cached sessions are only reused when it matches the cached `locId`.
 - Throws on network errors or API errors.
 
+### `client.getLocation()`
+
+Get location data only. Returns cached data if valid, otherwise fetches from the API.
+
+```typescript
+const location = await client.getLocation();
+// { city, state, stateCode, zipOptions } or null
+```
+
+```typescript
+interface TrackingLocation {
+  city: string;
+  state: string;
+  stateCode: string;
+  zipOptions?: string[]; // ordered by proximity, may be []
+}
+```
+
+### `client.getSessionAsync()`
+
+Kick off both requests and use each as soon as it resolves.
+
+```typescript
+const { session, location } = client.getSessionAsync();
+
+location.then((loc) => {
+  // show city/state ASAP
+  // optionally render loc?.zipOptions in a ZIP picker
+});
+
+session.then((sess) => {
+  // show phone number when ready
+});
+```
+
 ### `client.createCallIntent()`
 
 Create a short-lived call intent token for click/callback deterministic attribution.
@@ -174,6 +214,16 @@ client.onReady((session) => {
 });
 ```
 
+### `client.onLocationReady(callback)`
+
+Subscribe to location ready event. Callback is called once location data is available.
+
+```typescript
+client.onLocationReady((location) => {
+  // location is { city, state, stateCode, zipOptions } or null
+});
+```
+
 ### `client.setParams(params)`
 
 Set custom tracking parameters for conversion attribution.
@@ -230,7 +280,8 @@ Parameters are sent as a sorted query string for cache consistency:
 
 ## Caching Behavior
 
-- Cache key: `cf_tracking_v1_<siteKey>_<categoryId>`
+- Session cache key: `cf_tracking_v1_<siteKey>_<categoryId>`
+- Location cache key: `cf_location_v1_<siteKey>`
 - TTL: controlled by the server `expiresAt` response (currently 30 minutes)
 - Storage: localStorage (falls back to memory if unavailable)
 
@@ -261,6 +312,7 @@ import type {
   TrackingLocation,
   TrackingParams,
   ReadyCallback,
+  LocationReadyCallback,
   CallIntentResponse,
 } from '@callforge/tracking-client';
 ```

package/dist/index.d.mts

@@ -21,7 +21,10 @@ 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';
 /**
  * Tracking parameters for attribution (auto-captured + custom).
  */
@@ -49,21 +52,27 @@ interface TrackingSession {
     leaseId: string | null;
     /** Assigned phone number, or null if no number available */
     phoneNumber: string | null;
-    /** Location data, or null if location could not be resolved */
-    location: TrackingLocation | null;
 }
 /**
- * Internal API response format (includes expiresAt).
+ * Session API response format (includes expiresAt).
  */
-interface ApiResponse {
+interface ApiSessionResponse {
     sessionToken: string;
     leaseId: string | null;
     phoneNumber: string | null;
+    expiresAt: number;
+}
+/**
+ * Location API response format (includes expiresAt).
+ */
+interface ApiLocationResponse {
     location: {
         city: string;
         state: string;
         stateCode: string;
+        source: TrackingLocationSource;
     } | null;
+    zipOptions?: string[];
     expiresAt: number;
 }
 interface CallIntentResponse {
@@ -78,12 +87,14 @@ interface CallIntentResponse {
  * Callback function for onReady subscription.
  */
 type ReadyCallback = (session: TrackingSession) => void;
+type LocationReadyCallback = (location: TrackingLocation | null) => void;
 /**
  * Global window extension for preload promise and gtag.
  */
 declare global {
     interface Window {
-        __cfTracking?: Promise<ApiResponse>;
+        __cfTracking?: Promise<ApiSessionResponse>;
+        __cfTrackingLocation?: Promise<ApiLocationResponse>;
         gtag?: (command: 'get', targetId: string, fieldName: string, callback: (value: string) => void) => void;
     }
 }
@@ -91,7 +102,9 @@ declare global {
 declare class CallForge {
     private readonly config;
     private readonly cache;
+    private readonly locationCache;
     private sessionPromise;
+    private locationPromise;
     private customParams;
     private constructor();
     /**
@@ -103,6 +116,19 @@ declare class CallForge {
      * Returns cached data if valid, otherwise fetches from API.
      */
     getSession(): Promise<TrackingSession>;
+    /**
+     * Get location data only.
+     * Returns cached data if valid, otherwise fetches from API.
+     */
+    getLocation(): Promise<TrackingLocation | null>;
+    /**
+     * Kick off both session and location requests.
+     * Returns separate Promises so consumers can use each as soon as it resolves.
+     */
+    getSessionAsync(): {
+        session: Promise<TrackingSession>;
+        location: Promise<TrackingLocation | null>;
+    };
     /**
      * Create a short-lived call intent token for click/callback deterministic attribution.
      */
@@ -112,6 +138,11 @@ declare class CallForge {
      * Callback is called once session data is available.
      */
     onReady(callback: ReadyCallback): void;
+    /**
+     * Subscribe to location ready event.
+     * Callback is called once location data is available.
+     */
+    onLocationReady(callback: LocationReadyCallback): void;
     /**
      * Set custom tracking parameters for attribution.
      *
@@ -139,14 +170,20 @@ declare class CallForge {
      */
     private getGA4ClientIdFromCookie;
     private fetchSession;
+    private fetchLocation;
     private getLocationId;
     private getAutoParams;
     private fetchFromApi;
+    private fetchLocationFromApi;
     private saveToCache;
+    private saveLocationToCache;
+    private toTrackingLocation;
+    private normalizeZipOptions;
     private formatSession;
     private formatApiResponse;
     private syncParamsToCallForgeIfPossible;
     private buildUrl;
+    private buildLocationUrl;
 }
 
 /**
@@ -155,4 +192,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type CallIntentResponse, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type CallIntentResponse, type LocationReadyCallback, type ReadyCallback, type TrackingLocation, type TrackingLocationSource, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.d.ts

@@ -21,7 +21,10 @@ 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';
 /**
  * Tracking parameters for attribution (auto-captured + custom).
  */
@@ -49,21 +52,27 @@ interface TrackingSession {
     leaseId: string | null;
     /** Assigned phone number, or null if no number available */
     phoneNumber: string | null;
-    /** Location data, or null if location could not be resolved */
-    location: TrackingLocation | null;
 }
 /**
- * Internal API response format (includes expiresAt).
+ * Session API response format (includes expiresAt).
  */
-interface ApiResponse {
+interface ApiSessionResponse {
     sessionToken: string;
     leaseId: string | null;
     phoneNumber: string | null;
+    expiresAt: number;
+}
+/**
+ * Location API response format (includes expiresAt).
+ */
+interface ApiLocationResponse {
     location: {
         city: string;
         state: string;
         stateCode: string;
+        source: TrackingLocationSource;
     } | null;
+    zipOptions?: string[];
     expiresAt: number;
 }
 interface CallIntentResponse {
@@ -78,12 +87,14 @@ interface CallIntentResponse {
  * Callback function for onReady subscription.
  */
 type ReadyCallback = (session: TrackingSession) => void;
+type LocationReadyCallback = (location: TrackingLocation | null) => void;
 /**
  * Global window extension for preload promise and gtag.
  */
 declare global {
     interface Window {
-        __cfTracking?: Promise<ApiResponse>;
+        __cfTracking?: Promise<ApiSessionResponse>;
+        __cfTrackingLocation?: Promise<ApiLocationResponse>;
         gtag?: (command: 'get', targetId: string, fieldName: string, callback: (value: string) => void) => void;
     }
 }
@@ -91,7 +102,9 @@ declare global {
 declare class CallForge {
     private readonly config;
     private readonly cache;
+    private readonly locationCache;
     private sessionPromise;
+    private locationPromise;
     private customParams;
     private constructor();
     /**
@@ -103,6 +116,19 @@ declare class CallForge {
      * Returns cached data if valid, otherwise fetches from API.
      */
     getSession(): Promise<TrackingSession>;
+    /**
+     * Get location data only.
+     * Returns cached data if valid, otherwise fetches from API.
+     */
+    getLocation(): Promise<TrackingLocation | null>;
+    /**
+     * Kick off both session and location requests.
+     * Returns separate Promises so consumers can use each as soon as it resolves.
+     */
+    getSessionAsync(): {
+        session: Promise<TrackingSession>;
+        location: Promise<TrackingLocation | null>;
+    };
     /**
      * Create a short-lived call intent token for click/callback deterministic attribution.
      */
@@ -112,6 +138,11 @@ declare class CallForge {
      * Callback is called once session data is available.
      */
     onReady(callback: ReadyCallback): void;
+    /**
+     * Subscribe to location ready event.
+     * Callback is called once location data is available.
+     */
+    onLocationReady(callback: LocationReadyCallback): void;
     /**
      * Set custom tracking parameters for attribution.
      *
@@ -139,14 +170,20 @@ declare class CallForge {
      */
     private getGA4ClientIdFromCookie;
     private fetchSession;
+    private fetchLocation;
     private getLocationId;
     private getAutoParams;
     private fetchFromApi;
+    private fetchLocationFromApi;
     private saveToCache;
+    private saveLocationToCache;
+    private toTrackingLocation;
+    private normalizeZipOptions;
     private formatSession;
     private formatApiResponse;
     private syncParamsToCallForgeIfPossible;
     private buildUrl;
+    private buildLocationUrl;
 }
 
 /**
@@ -155,4 +192,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type CallIntentResponse, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type CallIntentResponse, type LocationReadyCallback, type ReadyCallback, type TrackingLocation, type TrackingLocationSource, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.js

@@ -138,6 +138,67 @@ var TrackingCache = class {
   }
 };
 
+// src/location-cache.ts
+var EXPIRY_BUFFER_MS2 = 3e4;
+var LocationCache = class {
+  constructor(siteKey) {
+    this.memoryCache = null;
+    this.useMemory = false;
+    const resolvedSiteKey = siteKey || (typeof window !== "undefined" ? window.location.hostname : "unknown-site");
+    this.key = `cf_location_v1_${resolvedSiteKey}`;
+    this.useMemory = !this.isLocalStorageAvailable();
+  }
+  isLocalStorageAvailable() {
+    try {
+      localStorage.setItem("__cf_test__", "1");
+      localStorage.removeItem("__cf_test__");
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+  get(locationId) {
+    const cached = this.read();
+    if (!cached) return null;
+    if (cached.expiresAt - EXPIRY_BUFFER_MS2 <= Date.now()) return null;
+    if (!locationId) return cached;
+    if (cached.locId !== locationId) return null;
+    return cached;
+  }
+  set(value) {
+    if (this.useMemory) {
+      this.memoryCache = value;
+      return;
+    }
+    try {
+      localStorage.setItem(this.key, JSON.stringify(value));
+    } catch (e) {
+      this.memoryCache = value;
+    }
+  }
+  clear() {
+    this.memoryCache = null;
+    if (!this.useMemory) {
+      try {
+        localStorage.removeItem(this.key);
+      } catch (e) {
+      }
+    }
+  }
+  read() {
+    if (this.useMemory) {
+      return this.memoryCache;
+    }
+    try {
+      const raw = localStorage.getItem(this.key);
+      if (!raw) return null;
+      return JSON.parse(raw);
+    } catch (e) {
+      return this.memoryCache;
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 var FETCH_TIMEOUT_MS = 1e4;
@@ -146,6 +207,7 @@ var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campai
 var CallForge = class _CallForge {
   constructor(config) {
     this.sessionPromise = null;
+    this.locationPromise = null;
     this.customParams = {};
     this.config = {
       categoryId: config.categoryId,
@@ -154,6 +216,7 @@ var CallForge = class _CallForge {
       siteKey: config.siteKey
     };
     this.cache = new TrackingCache(config.categoryId, config.siteKey);
+    this.locationCache = new LocationCache(config.siteKey);
     this.captureGA4ClientId();
     this.startGA4ClientIdPolling();
   }
@@ -174,6 +237,27 @@ var CallForge = class _CallForge {
     this.sessionPromise = this.fetchSession();
     return this.sessionPromise;
   }
+  /**
+   * Get location data only.
+   * Returns cached data if valid, otherwise fetches from API.
+   */
+  async getLocation() {
+    if (this.locationPromise) {
+      return this.locationPromise;
+    }
+    this.locationPromise = this.fetchLocation();
+    return this.locationPromise;
+  }
+  /**
+   * Kick off both session and location requests.
+   * Returns separate Promises so consumers can use each as soon as it resolves.
+   */
+  getSessionAsync() {
+    return {
+      session: this.getSession(),
+      location: this.getLocation()
+    };
+  }
   /**
    * Create a short-lived call intent token for click/callback deterministic attribution.
    */
@@ -209,6 +293,14 @@ var CallForge = class _CallForge {
     this.getSession().then(callback).catch(() => {
     });
   }
+  /**
+   * Subscribe to location ready event.
+   * Callback is called once location data is available.
+   */
+  onLocationReady(callback) {
+    this.getLocation().then(callback).catch(() => {
+    });
+  }
   /**
    * Set custom tracking parameters for attribution.
    *
@@ -331,6 +423,29 @@ var CallForge = class _CallForge {
     this.saveToCache(locationId, data, params);
     return this.formatApiResponse(data);
   }
+  async fetchLocation() {
+    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 = this.toTrackingLocation(data2.location, dataWithExtras.zipOptions);
+        this.saveLocationToCache(effectiveLocId, location2, data2.expiresAt);
+        return location2;
+      } catch (e) {
+      }
+    }
+    const cached = this.locationCache.get(locationId);
+    if (cached) {
+      return this.toTrackingLocation(cached.location, (_b = cached.location) == null ? void 0 : _b.zipOptions);
+    }
+    const data = await this.fetchLocationFromApi(locationId);
+    const location = this.toTrackingLocation(data.location, data.zipOptions);
+    this.saveLocationToCache(locationId, location, data.expiresAt);
+    return location;
+  }
   getLocationId() {
     if (typeof window === "undefined") return null;
     const params = new URLSearchParams(window.location.search);
@@ -365,33 +480,76 @@ var CallForge = class _CallForge {
       clearTimeout(timeoutId);
     }
   }
+  async fetchLocationFromApi(locationId) {
+    const url = this.buildLocationUrl(locationId);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const response = await fetch(url, {
+        credentials: "omit",
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   saveToCache(locationId, data, params) {
     const cached = {
       locId: locationId != null ? locationId : null,
       sessionToken: data.sessionToken,
       leaseId: data.leaseId,
       phoneNumber: data.phoneNumber,
-      location: data.location,
       expiresAt: data.expiresAt,
       tokenVersion: "v1",
       params
     };
     this.cache.set(cached);
   }
+  saveLocationToCache(locationId, location, expiresAt) {
+    this.locationCache.set({
+      locId: locationId != null ? locationId : null,
+      location,
+      expiresAt,
+      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,
       leaseId: cached.leaseId,
-      phoneNumber: cached.phoneNumber,
-      location: cached.location
+      phoneNumber: cached.phoneNumber
     };
   }
   formatApiResponse(data) {
     return {
       sessionToken: data.sessionToken,
       leaseId: data.leaseId,
-      phoneNumber: data.phoneNumber,
-      location: data.location
+      phoneNumber: data.phoneNumber
     };
   }
   async syncParamsToCallForgeIfPossible() {
@@ -424,6 +582,13 @@ var CallForge = class _CallForge {
     const qs = sorted.map((k) => `${k}=${encodeURIComponent(queryParams[k])}`).join("&");
     return `${endpoint}/v1/tracking/session?${qs}`;
   }
+  buildLocationUrl(locationId) {
+    const { endpoint } = this.config;
+    if (!locationId) {
+      return `${endpoint}/v1/tracking/location`;
+    }
+    return `${endpoint}/v1/tracking/location?loc_physical_ms=${encodeURIComponent(locationId)}`;
+  }
 };
 
 // src/preload.ts
@@ -453,6 +618,17 @@ if(m){try{var g=decodeURIComponent(m[1]||'');var s=g.split('.');if(s.length>=2){
 for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
 var site='${config.siteKey || ""}'||location.hostname||'unknown-site';
 var key='cf_tracking_v1_'+site+'_${categoryId}';
+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)){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){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{
 var c=JSON.parse(localStorage.getItem(key));
@@ -467,7 +643,7 @@ if(loc)url+='&loc_physical_ms='+loc;
 if(token)url+='&sessionToken='+encodeURIComponent(token);
 var ks=Object.keys(p).sort();
 for(var j=0;j<ks.length;j++)url+='&'+ks[j]+'='+encodeURIComponent(p[ks[j]]);
-window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){if(!r.ok)throw new Error('tracking preload failed');return r.json()}).then(function(d){d.params=p;d.locId=loc;try{localStorage.setItem(key,JSON.stringify({locId:loc,sessionToken:d.sessionToken,leaseId:d.leaseId,phoneNumber:d.phoneNumber,location:d.location,expiresAt:d.expiresAt,tokenVersion:'v1',params:p}))}catch(e){}return d});
+window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){if(!r.ok)throw new Error('tracking preload failed');return r.json()}).then(function(d){d.params=p;d.locId=loc;try{localStorage.setItem(key,JSON.stringify({locId:loc,sessionToken:d.sessionToken,leaseId:d.leaseId,phoneNumber:d.phoneNumber,expiresAt:d.expiresAt,tokenVersion:'v1',params:p}))}catch(e){}return d});
 })();`.replace(/\n/g, "");
   return `<link rel="preconnect" href="${endpoint}">
 <script>${script}</script>`;

package/dist/index.mjs

@@ -114,6 +114,67 @@ var TrackingCache = class {
   }
 };
 
+// src/location-cache.ts
+var EXPIRY_BUFFER_MS2 = 3e4;
+var LocationCache = class {
+  constructor(siteKey) {
+    this.memoryCache = null;
+    this.useMemory = false;
+    const resolvedSiteKey = siteKey || (typeof window !== "undefined" ? window.location.hostname : "unknown-site");
+    this.key = `cf_location_v1_${resolvedSiteKey}`;
+    this.useMemory = !this.isLocalStorageAvailable();
+  }
+  isLocalStorageAvailable() {
+    try {
+      localStorage.setItem("__cf_test__", "1");
+      localStorage.removeItem("__cf_test__");
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+  get(locationId) {
+    const cached = this.read();
+    if (!cached) return null;
+    if (cached.expiresAt - EXPIRY_BUFFER_MS2 <= Date.now()) return null;
+    if (!locationId) return cached;
+    if (cached.locId !== locationId) return null;
+    return cached;
+  }
+  set(value) {
+    if (this.useMemory) {
+      this.memoryCache = value;
+      return;
+    }
+    try {
+      localStorage.setItem(this.key, JSON.stringify(value));
+    } catch (e) {
+      this.memoryCache = value;
+    }
+  }
+  clear() {
+    this.memoryCache = null;
+    if (!this.useMemory) {
+      try {
+        localStorage.removeItem(this.key);
+      } catch (e) {
+      }
+    }
+  }
+  read() {
+    if (this.useMemory) {
+      return this.memoryCache;
+    }
+    try {
+      const raw = localStorage.getItem(this.key);
+      if (!raw) return null;
+      return JSON.parse(raw);
+    } catch (e) {
+      return this.memoryCache;
+    }
+  }
+};
+
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 var FETCH_TIMEOUT_MS = 1e4;
@@ -122,6 +183,7 @@ var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campai
 var CallForge = class _CallForge {
   constructor(config) {
     this.sessionPromise = null;
+    this.locationPromise = null;
     this.customParams = {};
     this.config = {
       categoryId: config.categoryId,
@@ -130,6 +192,7 @@ var CallForge = class _CallForge {
       siteKey: config.siteKey
     };
     this.cache = new TrackingCache(config.categoryId, config.siteKey);
+    this.locationCache = new LocationCache(config.siteKey);
     this.captureGA4ClientId();
     this.startGA4ClientIdPolling();
   }
@@ -150,6 +213,27 @@ var CallForge = class _CallForge {
     this.sessionPromise = this.fetchSession();
     return this.sessionPromise;
   }
+  /**
+   * Get location data only.
+   * Returns cached data if valid, otherwise fetches from API.
+   */
+  async getLocation() {
+    if (this.locationPromise) {
+      return this.locationPromise;
+    }
+    this.locationPromise = this.fetchLocation();
+    return this.locationPromise;
+  }
+  /**
+   * Kick off both session and location requests.
+   * Returns separate Promises so consumers can use each as soon as it resolves.
+   */
+  getSessionAsync() {
+    return {
+      session: this.getSession(),
+      location: this.getLocation()
+    };
+  }
   /**
    * Create a short-lived call intent token for click/callback deterministic attribution.
    */
@@ -185,6 +269,14 @@ var CallForge = class _CallForge {
     this.getSession().then(callback).catch(() => {
     });
   }
+  /**
+   * Subscribe to location ready event.
+   * Callback is called once location data is available.
+   */
+  onLocationReady(callback) {
+    this.getLocation().then(callback).catch(() => {
+    });
+  }
   /**
    * Set custom tracking parameters for attribution.
    *
@@ -307,6 +399,29 @@ var CallForge = class _CallForge {
     this.saveToCache(locationId, data, params);
     return this.formatApiResponse(data);
   }
+  async fetchLocation() {
+    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 = this.toTrackingLocation(data2.location, dataWithExtras.zipOptions);
+        this.saveLocationToCache(effectiveLocId, location2, data2.expiresAt);
+        return location2;
+      } catch (e) {
+      }
+    }
+    const cached = this.locationCache.get(locationId);
+    if (cached) {
+      return this.toTrackingLocation(cached.location, (_b = cached.location) == null ? void 0 : _b.zipOptions);
+    }
+    const data = await this.fetchLocationFromApi(locationId);
+    const location = this.toTrackingLocation(data.location, data.zipOptions);
+    this.saveLocationToCache(locationId, location, data.expiresAt);
+    return location;
+  }
   getLocationId() {
     if (typeof window === "undefined") return null;
     const params = new URLSearchParams(window.location.search);
@@ -341,33 +456,76 @@ var CallForge = class _CallForge {
       clearTimeout(timeoutId);
     }
   }
+  async fetchLocationFromApi(locationId) {
+    const url = this.buildLocationUrl(locationId);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      const response = await fetch(url, {
+        credentials: "omit",
+        signal: controller.signal
+      });
+      if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   saveToCache(locationId, data, params) {
     const cached = {
       locId: locationId != null ? locationId : null,
       sessionToken: data.sessionToken,
       leaseId: data.leaseId,
       phoneNumber: data.phoneNumber,
-      location: data.location,
       expiresAt: data.expiresAt,
       tokenVersion: "v1",
       params
     };
     this.cache.set(cached);
   }
+  saveLocationToCache(locationId, location, expiresAt) {
+    this.locationCache.set({
+      locId: locationId != null ? locationId : null,
+      location,
+      expiresAt,
+      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,
       leaseId: cached.leaseId,
-      phoneNumber: cached.phoneNumber,
-      location: cached.location
+      phoneNumber: cached.phoneNumber
     };
   }
   formatApiResponse(data) {
     return {
       sessionToken: data.sessionToken,
       leaseId: data.leaseId,
-      phoneNumber: data.phoneNumber,
-      location: data.location
+      phoneNumber: data.phoneNumber
     };
   }
   async syncParamsToCallForgeIfPossible() {
@@ -400,6 +558,13 @@ var CallForge = class _CallForge {
     const qs = sorted.map((k) => `${k}=${encodeURIComponent(queryParams[k])}`).join("&");
     return `${endpoint}/v1/tracking/session?${qs}`;
   }
+  buildLocationUrl(locationId) {
+    const { endpoint } = this.config;
+    if (!locationId) {
+      return `${endpoint}/v1/tracking/location`;
+    }
+    return `${endpoint}/v1/tracking/location?loc_physical_ms=${encodeURIComponent(locationId)}`;
+  }
 };
 
 // src/preload.ts
@@ -429,6 +594,17 @@ if(m){try{var g=decodeURIComponent(m[1]||'');var s=g.split('.');if(s.length>=2){
 for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
 var site='${config.siteKey || ""}'||location.hostname||'unknown-site';
 var key='cf_tracking_v1_'+site+'_${categoryId}';
+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)){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){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{
 var c=JSON.parse(localStorage.getItem(key));
@@ -443,7 +619,7 @@ if(loc)url+='&loc_physical_ms='+loc;
 if(token)url+='&sessionToken='+encodeURIComponent(token);
 var ks=Object.keys(p).sort();
 for(var j=0;j<ks.length;j++)url+='&'+ks[j]+'='+encodeURIComponent(p[ks[j]]);
-window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){if(!r.ok)throw new Error('tracking preload failed');return r.json()}).then(function(d){d.params=p;d.locId=loc;try{localStorage.setItem(key,JSON.stringify({locId:loc,sessionToken:d.sessionToken,leaseId:d.leaseId,phoneNumber:d.phoneNumber,location:d.location,expiresAt:d.expiresAt,tokenVersion:'v1',params:p}))}catch(e){}return d});
+window.__cfTracking=fetch(url,{credentials:'omit'}).then(function(r){if(!r.ok)throw new Error('tracking preload failed');return r.json()}).then(function(d){d.params=p;d.locId=loc;try{localStorage.setItem(key,JSON.stringify({locId:loc,sessionToken:d.sessionToken,leaseId:d.leaseId,phoneNumber:d.phoneNumber,expiresAt:d.expiresAt,tokenVersion:'v1',params:p}))}catch(e){}return d});
 })();`.replace(/\n/g, "");
   return `<link rel="preconnect" href="${endpoint}">
 <script>${script}</script>`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callforge/tracking-client",
-  "version": "0.6.3",
+  "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"
   }
-}
+}