@callforge/tracking-client 0.6.2 → 0.7.0

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,13 @@ 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" } or null
+
+// Phone session data (deterministic token + phone number)
+console.log(await session);  // { sessionToken, leaseId, phoneNumber }
 ```
 
 ### 3. Deterministic click/callback attribution (optional)
@@ -83,6 +87,7 @@ Requirements:
 
 How it works:
 - Extracts the GA4 `client_id` from the `_ga` cookie and sends it to CallForge as `ga4ClientId`.
+- Polls briefly after init to capture the cookie if Google Analytics sets it slightly later.
 - If `ga4MeasurementId` is configured and `gtag` is available, also uses `gtag('get', measurementId, 'client_id', ...)` (with a short retry window).
 - If `ga4ClientId` becomes available after a session is created, the client will refresh once to sync it to CallForge.
 
@@ -133,18 +138,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;
 }
 ```
 
@@ -154,6 +154,31 @@ 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 } or null
+```
+
+### `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
+});
+
+session.then((sess) => {
+  // show phone number when ready
+});
+```
+
 ### `client.createCallIntent()`
 
 Create a short-lived call intent token for click/callback deterministic attribution.
@@ -173,6 +198,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 } or null
+});
+```
+
 ### `client.setParams(params)`
 
 Set custom tracking parameters for conversion attribution.
@@ -187,6 +222,7 @@ client.setParams({
 
 Behavior:
 - Merges with existing params (later calls override earlier values).
+- If a session already exists (cached `sessionToken`), the client will refresh once to sync updated params server-side (best-effort).
 - Parameters are sent with every `getSession()` API request.
 - Persisted in localStorage alongside session data.
 
@@ -228,7 +264,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)
 
@@ -259,6 +296,7 @@ import type {
   TrackingLocation,
   TrackingParams,
   ReadyCallback,
+  LocationReadyCallback,
   CallIntentResponse,
 } from '@callforge/tracking-client';
 ```

package/dist/index.d.mts

@@ -22,6 +22,7 @@ interface TrackingLocation {
     /** State abbreviation (e.g., "GA") */
     stateCode: string;
 }
+type TrackingLocationSource = 'google_criteria' | 'cloudflare_geo';
 /**
  * Tracking parameters for attribution (auto-captured + custom).
  */
@@ -49,20 +50,25 @@ 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;
     expiresAt: number;
 }
@@ -78,12 +84,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 +99,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 +113,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.
      */
@@ -113,7 +136,15 @@ declare class CallForge {
      */
     onReady(callback: ReadyCallback): void;
     /**
-     * Set custom tracking parameters for the next session fetch.
+     * Subscribe to location ready event.
+     * Callback is called once location data is available.
+     */
+    onLocationReady(callback: LocationReadyCallback): void;
+    /**
+     * Set custom tracking parameters for attribution.
+     *
+     * When possible, the client will also refresh the session once to sync
+     * the updated params to CallForge (so server-side events can use them).
      */
     setParams(params: Record<string, string>): Promise<void>;
     /**
@@ -136,14 +167,18 @@ declare class CallForge {
      */
     private getGA4ClientIdFromCookie;
     private fetchSession;
+    private fetchLocation;
     private getLocationId;
     private getAutoParams;
     private fetchFromApi;
+    private fetchLocationFromApi;
     private saveToCache;
+    private saveLocationToCache;
     private formatSession;
     private formatApiResponse;
-    private syncGA4ClientIdIfNeeded;
+    private syncParamsToCallForgeIfPossible;
     private buildUrl;
+    private buildLocationUrl;
 }
 
 /**
@@ -152,4 +187,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

@@ -22,6 +22,7 @@ interface TrackingLocation {
     /** State abbreviation (e.g., "GA") */
     stateCode: string;
 }
+type TrackingLocationSource = 'google_criteria' | 'cloudflare_geo';
 /**
  * Tracking parameters for attribution (auto-captured + custom).
  */
@@ -49,20 +50,25 @@ 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;
     expiresAt: number;
 }
@@ -78,12 +84,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 +99,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 +113,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.
      */
@@ -113,7 +136,15 @@ declare class CallForge {
      */
     onReady(callback: ReadyCallback): void;
     /**
-     * Set custom tracking parameters for the next session fetch.
+     * Subscribe to location ready event.
+     * Callback is called once location data is available.
+     */
+    onLocationReady(callback: LocationReadyCallback): void;
+    /**
+     * Set custom tracking parameters for attribution.
+     *
+     * When possible, the client will also refresh the session once to sync
+     * the updated params to CallForge (so server-side events can use them).
      */
     setParams(params: Record<string, string>): Promise<void>;
     /**
@@ -136,14 +167,18 @@ declare class CallForge {
      */
     private getGA4ClientIdFromCookie;
     private fetchSession;
+    private fetchLocation;
     private getLocationId;
     private getAutoParams;
     private fetchFromApi;
+    private fetchLocationFromApi;
     private saveToCache;
+    private saveLocationToCache;
     private formatSession;
     private formatApiResponse;
-    private syncGA4ClientIdIfNeeded;
+    private syncParamsToCallForgeIfPossible;
     private buildUrl;
+    private buildLocationUrl;
 }
 
 /**
@@ -152,4 +187,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.
    */
@@ -210,23 +294,35 @@ var CallForge = class _CallForge {
     });
   }
   /**
-   * Set custom tracking parameters for the next session fetch.
+   * 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.
+   *
+   * When possible, the client will also refresh the session once to sync
+   * the updated params to CallForge (so server-side events can use them).
    */
   async setParams(params) {
     this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
-    if (params.ga4ClientId) {
-      const sync = async () => {
-        try {
-          await this.syncGA4ClientIdIfNeeded();
-        } catch (e) {
-        }
-      };
-      if (this.sessionPromise) {
-        void this.sessionPromise.then(sync).catch(() => {
-        });
-      } else {
-        void sync();
+    const sync = async () => {
+      try {
+        await this.syncParamsToCallForgeIfPossible();
+      } catch (e) {
+      }
+    };
+    if (this.sessionPromise) {
+      try {
+        await this.sessionPromise;
+      } catch (e) {
       }
+      await sync();
+    } else {
+      await sync();
     }
   }
   /**
@@ -259,7 +355,6 @@ var CallForge = class _CallForge {
     });
   }
   startGA4ClientIdPolling() {
-    if (!this.config.ga4MeasurementId) return;
     if (typeof window === "undefined") return;
     if (this.customParams.ga4ClientId) return;
     const MAX_ATTEMPTS = 20;
@@ -328,6 +423,37 @@ var CallForge = class _CallForge {
     this.saveToCache(locationId, data, params);
     return this.formatApiResponse(data);
   }
+  async fetchLocation() {
+    var _a;
+    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;
+        this.saveLocationToCache(effectiveLocId, location2, data2.expiresAt);
+        return location2;
+      } catch (e) {
+      }
+    }
+    const cached = this.locationCache.get(locationId);
+    if (cached) {
+      return cached.location;
+    }
+    const data = await this.fetchLocationFromApi(locationId);
+    const location = data.location ? {
+      city: data.location.city,
+      state: data.location.state,
+      stateCode: data.location.stateCode
+    } : null;
+    this.saveLocationToCache(locationId, location, data.expiresAt);
+    return location;
+  }
   getLocationId() {
     if (typeof window === "undefined") return null;
     const params = new URLSearchParams(window.location.search);
@@ -362,47 +488,64 @@ 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"
+    });
+  }
   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 syncGA4ClientIdIfNeeded() {
-    const ga4ClientId = this.customParams.ga4ClientId;
-    if (!ga4ClientId) return;
+  async syncParamsToCallForgeIfPossible() {
     const locationId = this.getLocationId();
     const sessionToken = this.cache.getSessionToken(locationId);
     if (!sessionToken) return;
     const autoParams = this.getAutoParams();
     const cachedParams = this.cache.getParams();
     const params = __spreadValues(__spreadValues(__spreadValues({}, autoParams), cachedParams), this.customParams);
-    if (cachedParams.ga4ClientId === params.ga4ClientId) {
-      return;
-    }
     const data = await this.fetchFromApi(locationId, sessionToken, params);
     this.saveToCache(locationId, data, params);
   }
@@ -426,6 +569,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
@@ -455,6 +605,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)){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});
+}
 var token=null;
 try{
 var c=JSON.parse(localStorage.getItem(key));
@@ -469,7 +630,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.
    */
@@ -186,23 +270,35 @@ var CallForge = class _CallForge {
     });
   }
   /**
-   * Set custom tracking parameters for the next session fetch.
+   * 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.
+   *
+   * When possible, the client will also refresh the session once to sync
+   * the updated params to CallForge (so server-side events can use them).
    */
   async setParams(params) {
     this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
-    if (params.ga4ClientId) {
-      const sync = async () => {
-        try {
-          await this.syncGA4ClientIdIfNeeded();
-        } catch (e) {
-        }
-      };
-      if (this.sessionPromise) {
-        void this.sessionPromise.then(sync).catch(() => {
-        });
-      } else {
-        void sync();
+    const sync = async () => {
+      try {
+        await this.syncParamsToCallForgeIfPossible();
+      } catch (e) {
+      }
+    };
+    if (this.sessionPromise) {
+      try {
+        await this.sessionPromise;
+      } catch (e) {
       }
+      await sync();
+    } else {
+      await sync();
     }
   }
   /**
@@ -235,7 +331,6 @@ var CallForge = class _CallForge {
     });
   }
   startGA4ClientIdPolling() {
-    if (!this.config.ga4MeasurementId) return;
     if (typeof window === "undefined") return;
     if (this.customParams.ga4ClientId) return;
     const MAX_ATTEMPTS = 20;
@@ -304,6 +399,37 @@ var CallForge = class _CallForge {
     this.saveToCache(locationId, data, params);
     return this.formatApiResponse(data);
   }
+  async fetchLocation() {
+    var _a;
+    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;
+        this.saveLocationToCache(effectiveLocId, location2, data2.expiresAt);
+        return location2;
+      } catch (e) {
+      }
+    }
+    const cached = this.locationCache.get(locationId);
+    if (cached) {
+      return cached.location;
+    }
+    const data = await this.fetchLocationFromApi(locationId);
+    const location = data.location ? {
+      city: data.location.city,
+      state: data.location.state,
+      stateCode: data.location.stateCode
+    } : null;
+    this.saveLocationToCache(locationId, location, data.expiresAt);
+    return location;
+  }
   getLocationId() {
     if (typeof window === "undefined") return null;
     const params = new URLSearchParams(window.location.search);
@@ -338,47 +464,64 @@ 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"
+    });
+  }
   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 syncGA4ClientIdIfNeeded() {
-    const ga4ClientId = this.customParams.ga4ClientId;
-    if (!ga4ClientId) return;
+  async syncParamsToCallForgeIfPossible() {
     const locationId = this.getLocationId();
     const sessionToken = this.cache.getSessionToken(locationId);
     if (!sessionToken) return;
     const autoParams = this.getAutoParams();
     const cachedParams = this.cache.getParams();
     const params = __spreadValues(__spreadValues(__spreadValues({}, autoParams), cachedParams), this.customParams);
-    if (cachedParams.ga4ClientId === params.ga4ClientId) {
-      return;
-    }
     const data = await this.fetchFromApi(locationId, sessionToken, params);
     this.saveToCache(locationId, data, params);
   }
@@ -402,6 +545,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
@@ -431,6 +581,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)){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});
+}
 var token=null;
 try{
 var c=JSON.parse(localStorage.getItem(key));
@@ -445,7 +606,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.2",
+  "version": "0.7.0",
   "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"
   }
-}
+}