npm - @callforge/tracking-client - Versions diffs - 0.7.0 → 0.8.0 - Mend

@callforge/tracking-client 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/README.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # @callforge/tracking-client
-Lightweight client library for the CallForge tracking API. Handles location-aware phone number assignment with aggressive caching and optional preload optimization.
+Lightweight client library for the CallForge tracking API. Handles location-aware phone number assignment with aggressive caching and preload optimization.
 ## Installation
@@ -10,11 +10,20 @@ npm install @callforge/tracking-client
 pnpm add @callforge/tracking-client
 ```
+## Lease Hardening Migration (v0.8+)
+This release adds bootstrap-token support for lease hardening and bot suppression.
+Client integration requirements:
+- Add the generated preload snippet in `<head>`. This prefetches bootstrap tokens and keeps session lookup fast.
+- Keep handling `phoneNumber` and `leaseId` separately. A request can return a phone number with `leaseId: null` when lease assignment is intentionally suppressed.
+- For attribution/scale metrics, treat `leaseId` as the source of truth for lease-backed traffic.
 ## Quick Start
-### 1. Add preload snippet to `<head>` (optional but recommended)
+### 1. Add preload snippet to `<head>` (required for deterministic leases)
-For optimal performance on static sites, add this snippet to your HTML `<head>`:
+For optimal performance and lease hardening, add this snippet to your HTML `<head>`:
 ```typescript
 import { getPreloadSnippet } from '@callforge/tracking-client';
@@ -43,7 +52,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 }
@@ -152,6 +167,7 @@ Behavior:
 - Returns cached data if valid.
 - Fetches fresh data when cache is missing/expired.
 - If `loc_physical_ms` is present in the URL, cached sessions are only reused when it matches the cached `locId`.
+- If lease assignment is suppressed (for example bot traffic or missing/invalid bootstrap), `phoneNumber` may be present while `leaseId` is `null`.
 - Throws on network errors or API errors.
 ### `client.getLocation()`
@@ -160,7 +176,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 +197,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 +230,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
 });
 ```
@@ -266,6 +292,7 @@ Parameters are sent as a sorted query string for cache consistency:
 - Session cache key: `cf_tracking_v1_<siteKey>_<categoryId>`
 - Location cache key: `cf_location_v1_<siteKey>`
+- Bootstrap cache key: `cf_bootstrap_v1_<siteKey>_<categoryId>`
 - TTL: controlled by the server `expiresAt` response (currently 30 minutes)
 - Storage: localStorage (falls back to memory if unavailable)

package/dist/index.d.mts CHANGED Viewed

@@ -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 {
@@ -100,6 +103,8 @@ declare class CallForge {
     private readonly config;
     private readonly cache;
     private readonly locationCache;
+    private readonly bootstrapCacheKey;
+    private bootstrapMemoryCache;
     private sessionPromise;
     private locationPromise;
     private customParams;
@@ -171,13 +176,19 @@ declare class CallForge {
     private getLocationId;
     private getAutoParams;
     private fetchFromApi;
+    private getBootstrapToken;
     private fetchLocationFromApi;
+    private getCachedBootstrapToken;
+    private saveBootstrapToken;
     private saveToCache;
     private saveLocationToCache;
+    private toTrackingLocation;
+    private normalizeZipOptions;
     private formatSession;
     private formatApiResponse;
     private syncParamsToCallForgeIfPossible;
     private buildUrl;
+    private buildBootstrapUrl;
     private buildLocationUrl;
 }

package/dist/index.d.ts CHANGED Viewed

@@ -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 {
@@ -100,6 +103,8 @@ declare class CallForge {
     private readonly config;
     private readonly cache;
     private readonly locationCache;
+    private readonly bootstrapCacheKey;
+    private bootstrapMemoryCache;
     private sessionPromise;
     private locationPromise;
     private customParams;
@@ -171,13 +176,19 @@ declare class CallForge {
     private getLocationId;
     private getAutoParams;
     private fetchFromApi;
+    private getBootstrapToken;
     private fetchLocationFromApi;
+    private getCachedBootstrapToken;
+    private saveBootstrapToken;
     private saveToCache;
     private saveLocationToCache;
+    private toTrackingLocation;
+    private normalizeZipOptions;
     private formatSession;
     private formatApiResponse;
     private syncParamsToCallForgeIfPossible;
     private buildUrl;
+    private buildBootstrapUrl;
     private buildLocationUrl;
 }

package/dist/index.js CHANGED Viewed

@@ -203,9 +203,11 @@ var LocationCache = class {
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 var FETCH_TIMEOUT_MS = 1e4;
 var CALL_INTENT_TIMEOUT_MS = 8e3;
+var BOOTSTRAP_TOKEN_EXPIRY_BUFFER_MS = 1e4;
 var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campaignid", "gad_source"];
 var CallForge = class _CallForge {
   constructor(config) {
+    this.bootstrapMemoryCache = null;
     this.sessionPromise = null;
     this.locationPromise = null;
     this.customParams = {};
@@ -215,8 +217,10 @@ var CallForge = class _CallForge {
       ga4MeasurementId: config.ga4MeasurementId,
       siteKey: config.siteKey
     };
+    const resolvedSiteKey = config.siteKey || (typeof window !== "undefined" ? window.location.hostname : "unknown-site");
     this.cache = new TrackingCache(config.categoryId, config.siteKey);
     this.locationCache = new LocationCache(config.siteKey);
+    this.bootstrapCacheKey = `cf_bootstrap_v1_${resolvedSiteKey}_${config.categoryId}`;
     this.captureGA4ClientId();
     this.startGA4ClientIdPolling();
   }
@@ -424,18 +428,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 +443,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;
   }
@@ -472,7 +468,43 @@ var CallForge = class _CallForge {
     return params;
   }
   async fetchFromApi(locationId, sessionToken, params) {
-    const url = this.buildUrl(locationId, sessionToken, params);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      let bootstrapToken = this.getCachedBootstrapToken();
+      let response = await fetch(
+        this.buildUrl(locationId, sessionToken, params, bootstrapToken),
+        {
+          credentials: "omit",
+          signal: controller.signal
+        }
+      );
+      if (response.status === 401) {
+        bootstrapToken = await this.getBootstrapToken(true);
+        if (bootstrapToken) {
+          response = await fetch(
+            this.buildUrl(locationId, sessionToken, params, bootstrapToken),
+            {
+              credentials: "omit",
+              signal: controller.signal
+            }
+          );
+        }
+      }
+      if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  async getBootstrapToken(forceRefresh = false) {
+    const cached = this.getCachedBootstrapToken();
+    if (!forceRefresh && cached) {
+      return cached;
+    }
+    const url = this.buildBootstrapUrl();
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
@@ -481,9 +513,14 @@ var CallForge = class _CallForge {
         signal: controller.signal
       });
       if (!response.ok) {
-        throw new Error(`API error: ${response.status} ${response.statusText}`);
+        return null;
       }
-      return await response.json();
+      const data = await response.json();
+      if (typeof data.bootstrapToken !== "string" || typeof data.expiresAt !== "number") {
+        return null;
+      }
+      this.saveBootstrapToken(data.bootstrapToken, data.expiresAt);
+      return data.bootstrapToken;
     } finally {
       clearTimeout(timeoutId);
     }
@@ -505,6 +542,40 @@ var CallForge = class _CallForge {
       clearTimeout(timeoutId);
     }
   }
+  getCachedBootstrapToken() {
+    var _a;
+    const now = Date.now();
+    const fromMemory = this.bootstrapMemoryCache;
+    if (fromMemory && fromMemory.expiresAt - BOOTSTRAP_TOKEN_EXPIRY_BUFFER_MS > now) {
+      return fromMemory.token;
+    }
+    try {
+      const raw = localStorage.getItem(this.bootstrapCacheKey);
+      if (!raw) return null;
+      const cached = JSON.parse(raw);
+      if (typeof cached.token !== "string" || typeof cached.expiresAt !== "number") {
+        return null;
+      }
+      if (cached.expiresAt - BOOTSTRAP_TOKEN_EXPIRY_BUFFER_MS <= now) {
+        return null;
+      }
+      return cached.token;
+    } catch (e) {
+      return (_a = fromMemory == null ? void 0 : fromMemory.token) != null ? _a : null;
+    }
+  }
+  saveBootstrapToken(token, expiresAt) {
+    const cached = {
+      token,
+      expiresAt,
+      tokenVersion: "b1"
+    };
+    this.bootstrapMemoryCache = cached;
+    try {
+      localStorage.setItem(this.bootstrapCacheKey, JSON.stringify(cached));
+    } catch (e) {
+    }
+  }
   saveToCache(locationId, data, params) {
     const cached = {
       locId: locationId != null ? locationId : null,
@@ -525,6 +596,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,
@@ -549,7 +641,7 @@ var CallForge = class _CallForge {
     const data = await this.fetchFromApi(locationId, sessionToken, params);
     this.saveToCache(locationId, data, params);
   }
-  buildUrl(locationId, sessionToken, params) {
+  buildUrl(locationId, sessionToken, params, bootstrapToken) {
     const { categoryId, endpoint } = this.config;
     const queryParams = {
       categoryId
@@ -560,6 +652,9 @@ var CallForge = class _CallForge {
     if (sessionToken) {
       queryParams.sessionToken = sessionToken;
     }
+    if (bootstrapToken) {
+      queryParams.bootstrapToken = bootstrapToken;
+    }
     for (const [key, value] of Object.entries(params)) {
       if (value !== void 0) {
         queryParams[key] = value;
@@ -569,6 +664,10 @@ var CallForge = class _CallForge {
     const qs = sorted.map((k) => `${k}=${encodeURIComponent(queryParams[k])}`).join("&");
     return `${endpoint}/v1/tracking/session?${qs}`;
   }
+  buildBootstrapUrl() {
+    const { endpoint, categoryId } = this.config;
+    return `${endpoint}/v1/tracking/bootstrap?categoryId=${encodeURIComponent(categoryId)}`;
+  }
   buildLocationUrl(locationId) {
     const { endpoint } = this.config;
     if (!locationId) {
@@ -606,15 +705,16 @@ 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;
+var bkey='cf_bootstrap_v1_'+site+'_${categoryId}';
 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{
@@ -625,12 +725,18 @@ token=(!loc||c.locId===loc)?c.sessionToken:null;
 var cp=c.params||{};
 p=Object.assign({},cp,p);
 }}catch(e){}
+var bt=null;
+try{
+var cb=JSON.parse(localStorage.getItem(bkey));
+if(cb&&typeof cb.token==='string'&&cb.expiresAt>Date.now()+10000)bt=cb.token;
+}catch(e){}
+var bp=bt?Promise.resolve({bootstrapToken:bt}):fetch('${endpoint}/v1/tracking/bootstrap?categoryId=${categoryId}',{credentials:'omit'}).then(function(r){if(!r.ok)return null;return r.json()}).then(function(b){if(!b||typeof b.bootstrapToken!=='string'||typeof b.expiresAt!=='number')return null;try{localStorage.setItem(bkey,JSON.stringify({token:b.bootstrapToken,expiresAt:b.expiresAt,tokenVersion:'b1'}))}catch(e){}return b}).catch(function(){return null});
 var url='${endpoint}/v1/tracking/session?categoryId=${categoryId}';
 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,expiresAt:d.expiresAt,tokenVersion:'v1',params:p}))}catch(e){}return d});
+window.__cfTracking=bp.then(function(b){if(b&&b.bootstrapToken)url+='&bootstrapToken='+encodeURIComponent(b.bootstrapToken);return 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 CHANGED Viewed

@@ -179,9 +179,11 @@ var LocationCache = class {
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 var FETCH_TIMEOUT_MS = 1e4;
 var CALL_INTENT_TIMEOUT_MS = 8e3;
+var BOOTSTRAP_TOKEN_EXPIRY_BUFFER_MS = 1e4;
 var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campaignid", "gad_source"];
 var CallForge = class _CallForge {
   constructor(config) {
+    this.bootstrapMemoryCache = null;
     this.sessionPromise = null;
     this.locationPromise = null;
     this.customParams = {};
@@ -191,8 +193,10 @@ var CallForge = class _CallForge {
       ga4MeasurementId: config.ga4MeasurementId,
       siteKey: config.siteKey
     };
+    const resolvedSiteKey = config.siteKey || (typeof window !== "undefined" ? window.location.hostname : "unknown-site");
     this.cache = new TrackingCache(config.categoryId, config.siteKey);
     this.locationCache = new LocationCache(config.siteKey);
+    this.bootstrapCacheKey = `cf_bootstrap_v1_${resolvedSiteKey}_${config.categoryId}`;
     this.captureGA4ClientId();
     this.startGA4ClientIdPolling();
   }
@@ -400,18 +404,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 +419,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;
   }
@@ -448,7 +444,43 @@ var CallForge = class _CallForge {
     return params;
   }
   async fetchFromApi(locationId, sessionToken, params) {
-    const url = this.buildUrl(locationId, sessionToken, params);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    try {
+      let bootstrapToken = this.getCachedBootstrapToken();
+      let response = await fetch(
+        this.buildUrl(locationId, sessionToken, params, bootstrapToken),
+        {
+          credentials: "omit",
+          signal: controller.signal
+        }
+      );
+      if (response.status === 401) {
+        bootstrapToken = await this.getBootstrapToken(true);
+        if (bootstrapToken) {
+          response = await fetch(
+            this.buildUrl(locationId, sessionToken, params, bootstrapToken),
+            {
+              credentials: "omit",
+              signal: controller.signal
+            }
+          );
+        }
+      }
+      if (!response.ok) {
+        throw new Error(`API error: ${response.status} ${response.statusText}`);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  async getBootstrapToken(forceRefresh = false) {
+    const cached = this.getCachedBootstrapToken();
+    if (!forceRefresh && cached) {
+      return cached;
+    }
+    const url = this.buildBootstrapUrl();
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
     try {
@@ -457,9 +489,14 @@ var CallForge = class _CallForge {
         signal: controller.signal
       });
       if (!response.ok) {
-        throw new Error(`API error: ${response.status} ${response.statusText}`);
+        return null;
       }
-      return await response.json();
+      const data = await response.json();
+      if (typeof data.bootstrapToken !== "string" || typeof data.expiresAt !== "number") {
+        return null;
+      }
+      this.saveBootstrapToken(data.bootstrapToken, data.expiresAt);
+      return data.bootstrapToken;
     } finally {
       clearTimeout(timeoutId);
     }
@@ -481,6 +518,40 @@ var CallForge = class _CallForge {
       clearTimeout(timeoutId);
     }
   }
+  getCachedBootstrapToken() {
+    var _a;
+    const now = Date.now();
+    const fromMemory = this.bootstrapMemoryCache;
+    if (fromMemory && fromMemory.expiresAt - BOOTSTRAP_TOKEN_EXPIRY_BUFFER_MS > now) {
+      return fromMemory.token;
+    }
+    try {
+      const raw = localStorage.getItem(this.bootstrapCacheKey);
+      if (!raw) return null;
+      const cached = JSON.parse(raw);
+      if (typeof cached.token !== "string" || typeof cached.expiresAt !== "number") {
+        return null;
+      }
+      if (cached.expiresAt - BOOTSTRAP_TOKEN_EXPIRY_BUFFER_MS <= now) {
+        return null;
+      }
+      return cached.token;
+    } catch (e) {
+      return (_a = fromMemory == null ? void 0 : fromMemory.token) != null ? _a : null;
+    }
+  }
+  saveBootstrapToken(token, expiresAt) {
+    const cached = {
+      token,
+      expiresAt,
+      tokenVersion: "b1"
+    };
+    this.bootstrapMemoryCache = cached;
+    try {
+      localStorage.setItem(this.bootstrapCacheKey, JSON.stringify(cached));
+    } catch (e) {
+    }
+  }
   saveToCache(locationId, data, params) {
     const cached = {
       locId: locationId != null ? locationId : null,
@@ -501,6 +572,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,
@@ -525,7 +617,7 @@ var CallForge = class _CallForge {
     const data = await this.fetchFromApi(locationId, sessionToken, params);
     this.saveToCache(locationId, data, params);
   }
-  buildUrl(locationId, sessionToken, params) {
+  buildUrl(locationId, sessionToken, params, bootstrapToken) {
     const { categoryId, endpoint } = this.config;
     const queryParams = {
       categoryId
@@ -536,6 +628,9 @@ var CallForge = class _CallForge {
     if (sessionToken) {
       queryParams.sessionToken = sessionToken;
     }
+    if (bootstrapToken) {
+      queryParams.bootstrapToken = bootstrapToken;
+    }
     for (const [key, value] of Object.entries(params)) {
       if (value !== void 0) {
         queryParams[key] = value;
@@ -545,6 +640,10 @@ var CallForge = class _CallForge {
     const qs = sorted.map((k) => `${k}=${encodeURIComponent(queryParams[k])}`).join("&");
     return `${endpoint}/v1/tracking/session?${qs}`;
   }
+  buildBootstrapUrl() {
+    const { endpoint, categoryId } = this.config;
+    return `${endpoint}/v1/tracking/bootstrap?categoryId=${encodeURIComponent(categoryId)}`;
+  }
   buildLocationUrl(locationId) {
     const { endpoint } = this.config;
     if (!locationId) {
@@ -582,15 +681,16 @@ 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;
+var bkey='cf_bootstrap_v1_'+site+'_${categoryId}';
 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{
@@ -601,12 +701,18 @@ token=(!loc||c.locId===loc)?c.sessionToken:null;
 var cp=c.params||{};
 p=Object.assign({},cp,p);
 }}catch(e){}
+var bt=null;
+try{
+var cb=JSON.parse(localStorage.getItem(bkey));
+if(cb&&typeof cb.token==='string'&&cb.expiresAt>Date.now()+10000)bt=cb.token;
+}catch(e){}
+var bp=bt?Promise.resolve({bootstrapToken:bt}):fetch('${endpoint}/v1/tracking/bootstrap?categoryId=${categoryId}',{credentials:'omit'}).then(function(r){if(!r.ok)return null;return r.json()}).then(function(b){if(!b||typeof b.bootstrapToken!=='string'||typeof b.expiresAt!=='number')return null;try{localStorage.setItem(bkey,JSON.stringify({token:b.bootstrapToken,expiresAt:b.expiresAt,tokenVersion:'b1'}))}catch(e){}return b}).catch(function(){return null});
 var url='${endpoint}/v1/tracking/session?categoryId=${categoryId}';
 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,expiresAt:d.expiresAt,tokenVersion:'v1',params:p}))}catch(e){}return d});
+window.__cfTracking=bp.then(function(b){if(b&&b.bootstrapToken)url+='&bootstrapToken='+encodeURIComponent(b.bootstrapToken);return 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 CHANGED Viewed

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