@callforge/tracking-client 0.5.1 → 0.6.1

package/README.md

@@ -1,8 +1,6 @@
 # @callforge/tracking-client
 
-Lightweight client library for the CallForge tracking API. Handles location-aware phone number assignment with aggressive caching and preload optimization.
-
-**v0.4.1** - Simplified GA4 capture: uses gtag callback when `ga4MeasurementId` configured, no polling fallback.
+Lightweight client library for the CallForge tracking API. Handles location-aware phone number assignment with aggressive caching and optional preload optimization.
 
 ## Installation
 
@@ -26,12 +24,13 @@ const snippet = getPreloadSnippet({ categoryId: 'your-category-id' });
 ```
 
 Generated HTML:
+
 ```html
 <link rel="preconnect" href="https://tracking.callforge.io">
 <script>/* preload script */</script>
 ```
 
-### 2. Initialize and use the client
+### 2. Initialize and fetch a tracking session
 
 ```typescript
 import { CallForge } from '@callforge/tracking-client';
@@ -41,40 +40,52 @@ const client = CallForge.init({
   // endpoint: 'https://tracking-dev.callforge.io', // Optional: override for dev
 });
 
-// Promise style
 const session = await client.getSession();
 console.log(session.phoneNumber);  // "+17705550000" or null
 console.log(session.location);     // { city: "Woodstock", state: "Georgia", stateCode: "GA" } or null
+```
 
-// Subscription style
-client.onReady((session) => {
-  document.getElementById('phone').textContent = session.phoneNumber;
-  document.getElementById('city').textContent = session.location?.city;
+### 3. Deterministic click/callback attribution (optional)
+
+If you initiate calls programmatically (click-to-call / callback), you can request a short-lived `callIntentToken`. CallForge will consume this once to deterministically map the call back to the web session that requested it.
+
+```typescript
+// In the browser:
+const { callIntentToken } = await client.createCallIntent();
+
+// Send to your backend and attach to the call you initiate
+await fetch('/api/callback', {
+  method: 'POST',
+  headers: { 'Content-Type': 'application/json' },
+  body: JSON.stringify({ callIntentToken }),
 });
 ```
 
-### 3. GA4 Integration
+Notes:
+- `callIntentToken` is short-lived and single-use.
+- Treat it as an opaque secret (do not log it).
+
+### 4. GA4 Integration
 
 To enable GA4 call event tracking, provide your GA4 Measurement ID:
 
 ```typescript
 const client = CallForge.init({
   categoryId: 'your-category-id',
-  ga4MeasurementId: 'G-XXXXXXXXXX',  // Required for GA4 integration
+  ga4MeasurementId: 'G-XXXXXXXXXX',
 });
 ```
 
-**Requirements:**
-1. Google Analytics 4 must be installed on your site (`gtag.js`)
-2. Provide `ga4MeasurementId` in client config
-3. Configure GA4 credentials in CallForge dashboard (Categories → Edit → GA4 tab)
+Requirements:
+1. Google Analytics 4 must be installed on your site (`gtag.js`).
+2. Provide `ga4MeasurementId` in client config.
+3. Configure GA4 credentials in CallForge dashboard.
 
-**How it works:**
-- Uses `gtag('get', measurementId, 'client_id', callback)` to capture the GA4 client ID
-- Callback fires when GA4 is ready - no polling needed
-- Client ID is automatically sent to CallForge for call event attribution
+How it works:
+- Uses `gtag('get', measurementId, 'client_id', callback)` to capture the GA4 client ID.
+- Client ID is sent to CallForge for call event attribution.
 
-**Manual override:** If you need to pass a custom GA4 client ID:
+Manual override:
 
 ```typescript
 client.setParams({
@@ -82,7 +93,7 @@ client.setParams({
 });
 ```
 
-### 4. Track conversion parameters (optional)
+### 5. Track conversion parameters (optional)
 
 The client automatically captures ad platform click IDs from the URL:
 
@@ -95,14 +106,13 @@ The client automatically captures ad platform click IDs from the URL:
 You can also add custom parameters:
 
 ```typescript
-// Add custom tracking parameters
 client.setParams({
   customerId: '456',
   landingPage: 'pricing',
 });
 
 // Parameters are automatically sent with every API request
-const session = await client.getSession();
+await client.getSession();
 ```
 
 ## API Reference
@@ -115,18 +125,19 @@ Initialize the tracking client.
 interface CallForgeConfig {
   categoryId: string;        // Required - which number pool to use
   endpoint?: string;         // Optional - defaults to 'https://tracking.callforge.io'
-  ga4MeasurementId?: string; // Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX")
-                             // Enables gtag callback instead of cookie polling
+  siteKey?: string;          // Optional - cache partition key (defaults to window.location.hostname)
+  ga4MeasurementId?: string; // Optional - GA4 Measurement ID (e.g., 'G-XXXXXXXXXX')
 }
 ```
 
 ### `client.getSession()`
 
-Get tracking session data. Returns cached data if valid, otherwise fetches from API.
+Get tracking session data. Returns cached data if valid, otherwise fetches from the API.
 
 ```typescript
 interface TrackingSession {
-  sessionId: string | null;
+  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;
@@ -136,11 +147,20 @@ interface TrackingSession {
 }
 ```
 
-**Behavior:**
-- Returns `null` values immediately if no `loc_physical_ms` in URL (no API call)
-- Returns cached data if valid (same location, not expired)
-- Fetches fresh data if cache expired or location changed
-- Throws on network errors or API errors
+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`.
+- Throws on network errors or API errors.
+
+### `client.createCallIntent()`
+
+Create a short-lived call intent token for click/callback deterministic attribution.
+
+```typescript
+const intent = await client.createCallIntent();
+console.log(intent.callIntentToken);
+```
 
 ### `client.onReady(callback)`
 
@@ -164,11 +184,10 @@ client.setParams({
 });
 ```
 
-**Behavior:**
-- Merges with existing params (later calls override earlier values)
-- Parameters are sent with every `getSession()` API request
-- Persisted in localStorage alongside session data
-- Auto-captured params (gclid, etc.) are included automatically
+Behavior:
+- Merges with existing params (later calls override earlier values).
+- Parameters are sent with every `getSession()` API request.
+- Persisted in localStorage alongside session data.
 
 ### `getPreloadSnippet(config)`
 
@@ -180,6 +199,7 @@ import { getPreloadSnippet } from '@callforge/tracking-client';
 const html = getPreloadSnippet({
   categoryId: 'your-category-id',
   endpoint: 'https://tracking.callforge.io', // Optional
+  siteKey: 'example.com', // Optional
 });
 ```
 
@@ -194,32 +214,22 @@ The client automatically extracts these parameters from the URL:
 | `gclid` | Google Ads Click ID |
 | `gbraid` | Google app-to-web (iOS 14+) |
 | `wbraid` | Google web-to-app |
-| `msclkid` | Microsoft/Bing Ads |
-| `fbclid` | Facebook/Meta Ads |
-
-**Note:** `ga4ClientId` is captured via `gtag('get')` callback when `ga4MeasurementId` is configured.
-
-### Persistence
-
-- Parameters are stored in localStorage alongside the session
-- On subsequent visits, cached params are used (URL may no longer have them)
-- Custom params via `setParams()` merge with auto-captured params
-- Later values override earlier ones (custom > cached > auto-captured)
+| `msclkid` | Microsoft/Bing Ads Click ID |
+| `fbclid` | Facebook/Meta Ads Click ID |
 
 ### API Request Format
 
-Parameters are sent as sorted query string for cache consistency:
+Parameters are sent as a sorted query string for cache consistency:
 
 ```
-/v1/tracking/session?categoryId=cat-123&fbclid=456&gclid=abc&loc_physical_ms=1014221
+/v1/tracking/session?categoryId=cat-123&fbclid=456&gclid=abc&loc_physical_ms=1014221&sessionToken=...
 ```
 
 ## Caching Behavior
 
-- **Cache key:** `loc_physical_ms` parameter from URL
-- **TTL:** 30 minutes (controlled by server)
-- **Storage:** localStorage (falls back to memory if unavailable)
-- **Invalidation:** Cache clears when location changes
+- Cache key: `cf_tracking_v1_<siteKey>_<categoryId>`
+- TTL: controlled by the server `expiresAt` response (currently 30 minutes)
+- Storage: localStorage (falls back to memory if unavailable)
 
 ## Error Handling
 
@@ -229,7 +239,7 @@ try {
   if (session.phoneNumber) {
     // Use phone number
   } else {
-    // No phone number available for this location
+    // No phone number available
   }
 } catch (err) {
   // Network error or API error
@@ -248,52 +258,10 @@ import type {
   TrackingLocation,
   TrackingParams,
   ReadyCallback,
+  CallIntentResponse,
 } from '@callforge/tracking-client';
 ```
 
-### TrackingParams
-
-```typescript
-interface TrackingParams {
-  gclid?: string;       // Google Ads Click ID
-  gbraid?: string;      // Google app-to-web (iOS 14+)
-  wbraid?: string;      // Google web-to-app
-  msclkid?: string;     // Microsoft/Bing Ads
-  fbclid?: string;      // Facebook/Meta Ads
-  ga4ClientId?: string; // Google Analytics 4 Client ID (auto-captured via gtag callback)
-  [key: string]: string | undefined;  // Custom params
-}
-```
-
-## GA4 Events
-
-When GA4 is configured for a category, CallForge sends these events to Google Analytics 4 via the Measurement Protocol:
-
-| Event Name | When Sent | Description |
-|------------|-----------|-------------|
-| `phone_call` | Call initiated | A phone call was placed to the tracking number |
-| `call_conversion` | Call qualified | The call met conversion criteria (e.g., duration threshold) |
-| `call_conversion_billable` | Call billable | The call was both qualified AND billable |
-
-**Event Parameters:**
-
-All events include:
-- `session_id` - CallForge session ID
-- `phone_number` - Tracking number dialed
-- `category` - Category slug
-
-`call_conversion` and `call_conversion_billable` also include:
-- `call_duration` - Call duration in seconds
-- `buyer` - Buyer the call was routed to (if applicable)
-
-**Setup:**
-1. In Google Analytics 4, go to Admin → Data Streams → your web stream
-2. Copy the **Measurement ID** (e.g., `G-XXXXXXXXXX`)
-3. Go to Admin → Data Streams → Measurement Protocol API secrets → Create
-4. Copy the **API Secret**
-5. In CallForge dashboard: Categories → Edit category → GA4 tab
-6. Enable GA4, paste Measurement ID and API Secret, save
-
 ## Environment URLs
 
 | Environment | Endpoint |

package/dist/index.d.mts

@@ -6,6 +6,8 @@ interface CallForgeConfig {
     categoryId: string;
     /** Optional - API endpoint. Defaults to 'https://tracking.callforge.io' */
     endpoint?: string;
+    /** Optional - explicit site key for cache partitioning. Defaults to window.location.hostname */
+    siteKey?: string;
     /** Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX"). Enables gtag callback instead of cookie polling. */
     ga4MeasurementId?: string;
 }
@@ -41,8 +43,10 @@ interface TrackingParams {
  * Session data returned by getSession().
  */
 interface TrackingSession {
-    /** Session ID from the tracking API */
-    sessionId: string | null;
+    /** Signed session token */
+    sessionToken: string;
+    /** Lease ID for deterministic number assignment */
+    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 */
@@ -52,7 +56,8 @@ interface TrackingSession {
  * Internal API response format (includes expiresAt).
  */
 interface ApiResponse {
-    sessionId: string;
+    sessionToken: string;
+    leaseId: string | null;
     phoneNumber: string | null;
     location: {
         city: string;
@@ -61,6 +66,14 @@ interface ApiResponse {
     } | null;
     expiresAt: number;
 }
+interface CallIntentResponse {
+    callIntentToken: string;
+    intentId: string;
+    sessionId: string;
+    leaseId: string | null;
+    expiresAt: string;
+    attributionVersion: 'v1';
+}
 /**
  * Callback function for onReady subscription.
  */
@@ -80,8 +93,6 @@ declare class CallForge {
     private readonly cache;
     private sessionPromise;
     private customParams;
-    private sessionId;
-    private sessionCreated;
     private constructor();
     /**
      * Initialize the CallForge tracking client.
@@ -92,22 +103,23 @@ declare class CallForge {
      * Returns cached data if valid, otherwise fetches from API.
      */
     getSession(): Promise<TrackingSession>;
+    /**
+     * Create a short-lived call intent token for click/callback deterministic attribution.
+     */
+    createCallIntent(): Promise<CallIntentResponse>;
     /**
      * Subscribe to session ready event.
      * Callback is called once session data is available.
      */
     onReady(callback: ReadyCallback): void;
     /**
-     * Set custom tracking parameters.
-     * If session already exists, sends PATCH to update.
-     * Otherwise queues params for next session request.
+     * Set custom tracking parameters for the next session fetch.
      */
     setParams(params: Record<string, string>): Promise<void>;
     /**
      * Get the currently queued custom params.
      */
     getQueuedParams(): TrackingParams;
-    private patchSession;
     /**
      * Capture the GA4 client ID using gtag callback.
      * Only runs if ga4MeasurementId is configured.
@@ -126,18 +138,7 @@ declare class CallForge {
 /**
  * Generate HTML snippet for preloading tracking data.
  * Add this to the <head> of your HTML for optimal performance.
- *
- * The generated snippet:
- * - Checks for loc_physical_ms URL parameter
- * - Checks localStorage cache for valid session
- * - If cache valid, resolves Promise.resolve(cached) immediately
- * - If cache expired but same location, includes sessionId for refresh
- * - Otherwise fetches fresh session data
- * - Sets window.__cfTracking with the session promise
- *
- * @throws {Error} If categoryId contains invalid characters
- * @throws {Error} If endpoint is not a valid HTTPS URL
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type CallIntentResponse, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.d.ts

@@ -6,6 +6,8 @@ interface CallForgeConfig {
     categoryId: string;
     /** Optional - API endpoint. Defaults to 'https://tracking.callforge.io' */
     endpoint?: string;
+    /** Optional - explicit site key for cache partitioning. Defaults to window.location.hostname */
+    siteKey?: string;
     /** Optional - GA4 Measurement ID (e.g., "G-XXXXXXXXXX"). Enables gtag callback instead of cookie polling. */
     ga4MeasurementId?: string;
 }
@@ -41,8 +43,10 @@ interface TrackingParams {
  * Session data returned by getSession().
  */
 interface TrackingSession {
-    /** Session ID from the tracking API */
-    sessionId: string | null;
+    /** Signed session token */
+    sessionToken: string;
+    /** Lease ID for deterministic number assignment */
+    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 */
@@ -52,7 +56,8 @@ interface TrackingSession {
  * Internal API response format (includes expiresAt).
  */
 interface ApiResponse {
-    sessionId: string;
+    sessionToken: string;
+    leaseId: string | null;
     phoneNumber: string | null;
     location: {
         city: string;
@@ -61,6 +66,14 @@ interface ApiResponse {
     } | null;
     expiresAt: number;
 }
+interface CallIntentResponse {
+    callIntentToken: string;
+    intentId: string;
+    sessionId: string;
+    leaseId: string | null;
+    expiresAt: string;
+    attributionVersion: 'v1';
+}
 /**
  * Callback function for onReady subscription.
  */
@@ -80,8 +93,6 @@ declare class CallForge {
     private readonly cache;
     private sessionPromise;
     private customParams;
-    private sessionId;
-    private sessionCreated;
     private constructor();
     /**
      * Initialize the CallForge tracking client.
@@ -92,22 +103,23 @@ declare class CallForge {
      * Returns cached data if valid, otherwise fetches from API.
      */
     getSession(): Promise<TrackingSession>;
+    /**
+     * Create a short-lived call intent token for click/callback deterministic attribution.
+     */
+    createCallIntent(): Promise<CallIntentResponse>;
     /**
      * Subscribe to session ready event.
      * Callback is called once session data is available.
      */
     onReady(callback: ReadyCallback): void;
     /**
-     * Set custom tracking parameters.
-     * If session already exists, sends PATCH to update.
-     * Otherwise queues params for next session request.
+     * Set custom tracking parameters for the next session fetch.
      */
     setParams(params: Record<string, string>): Promise<void>;
     /**
      * Get the currently queued custom params.
      */
     getQueuedParams(): TrackingParams;
-    private patchSession;
     /**
      * Capture the GA4 client ID using gtag callback.
      * Only runs if ga4MeasurementId is configured.
@@ -126,18 +138,7 @@ declare class CallForge {
 /**
  * Generate HTML snippet for preloading tracking data.
  * Add this to the <head> of your HTML for optimal performance.
- *
- * The generated snippet:
- * - Checks for loc_physical_ms URL parameter
- * - Checks localStorage cache for valid session
- * - If cache valid, resolves Promise.resolve(cached) immediately
- * - If cache expired but same location, includes sessionId for refresh
- * - Otherwise fetches fresh session data
- * - Sets window.__cfTracking with the session promise
- *
- * @throws {Error} If categoryId contains invalid characters
- * @throws {Error} If endpoint is not a valid HTTPS URL
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
 
-export { CallForge, type CallForgeConfig, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type CallIntentResponse, type ReadyCallback, type TrackingLocation, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.js

@@ -42,10 +42,11 @@ module.exports = __toCommonJS(index_exports);
 // src/cache.ts
 var EXPIRY_BUFFER_MS = 3e4;
 var TrackingCache = class {
-  constructor(categoryId) {
+  constructor(categoryId, siteKey) {
     this.memoryCache = null;
     this.useMemory = false;
-    this.key = `cf_tracking_${categoryId}`;
+    const resolvedSiteKey = siteKey || (typeof window !== "undefined" ? window.location.hostname : "unknown-site");
+    this.key = `cf_tracking_v1_${resolvedSiteKey}_${categoryId}`;
     this.useMemory = !this.isLocalStorageAvailable();
   }
   isLocalStorageAvailable() {
@@ -78,17 +79,15 @@ var TrackingCache = class {
     return cached;
   }
   /**
-   * Get sessionId for refresh if location matches (regardless of expiry).
-   * Used when cache is expired but location is same - send sessionId to server.
-   *
-   * Only returns sessionId if locationId is provided AND matches cached locId.
-   * (IP-based sessions don't send sessionId for refresh since location may differ)
+   * Get sessionToken for refresh if location matches (regardless of expiry).
+   * Used when cache is expired but location is same - send token to server.
    */
-  getSessionId(locationId) {
+  getSessionToken(locationId) {
     const cached = this.read();
     if (!cached) return null;
-    if (!locationId || cached.locId !== locationId) return null;
-    return cached.sessionId;
+    if (!locationId) return cached.sessionToken;
+    if (cached.locId !== locationId) return null;
+    return cached.sessionToken;
   }
   /**
    * Get cached params (for merging with new params).
@@ -142,19 +141,19 @@ var TrackingCache = class {
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 var FETCH_TIMEOUT_MS = 1e4;
+var CALL_INTENT_TIMEOUT_MS = 8e3;
 var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campaignid", "gad_source"];
 var CallForge = class _CallForge {
   constructor(config) {
     this.sessionPromise = null;
     this.customParams = {};
-    this.sessionId = null;
-    this.sessionCreated = false;
     this.config = {
       categoryId: config.categoryId,
       endpoint: config.endpoint || DEFAULT_ENDPOINT,
-      ga4MeasurementId: config.ga4MeasurementId
+      ga4MeasurementId: config.ga4MeasurementId,
+      siteKey: config.siteKey
     };
-    this.cache = new TrackingCache(config.categoryId);
+    this.cache = new TrackingCache(config.categoryId, config.siteKey);
     this.captureGA4ClientId();
   }
   /**
@@ -174,6 +173,33 @@ var CallForge = class _CallForge {
     this.sessionPromise = this.fetchSession();
     return this.sessionPromise;
   }
+  /**
+   * Create a short-lived call intent token for click/callback deterministic attribution.
+   */
+  async createCallIntent() {
+    const session = await this.getSession();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), CALL_INTENT_TIMEOUT_MS);
+    try {
+      const response = await fetch(`${this.config.endpoint}/v1/tracking/call-intent`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        credentials: "omit",
+        signal: controller.signal,
+        body: JSON.stringify({
+          sessionToken: session.sessionToken
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`Call intent API error: ${response.status} ${response.statusText}`);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * Subscribe to session ready event.
    * Callback is called once session data is available.
@@ -183,15 +209,10 @@ var CallForge = class _CallForge {
     });
   }
   /**
-   * Set custom tracking parameters.
-   * If session already exists, sends PATCH to update.
-   * Otherwise queues params for next session request.
+   * Set custom tracking parameters for the next session fetch.
    */
   async setParams(params) {
     this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
-    if (this.sessionCreated && this.sessionId) {
-      await this.patchSession(params);
-    }
   }
   /**
    * Get the currently queued custom params.
@@ -199,23 +220,6 @@ var CallForge = class _CallForge {
   getQueuedParams() {
     return __spreadValues({}, this.customParams);
   }
-  async patchSession(params) {
-    try {
-      const response = await fetch(
-        `${this.config.endpoint}/v1/tracking/session/${this.sessionId}`,
-        {
-          method: "PATCH",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(params)
-        }
-      );
-      if (!response.ok) {
-        console.warn("[CallForge] Failed to patch session:", response.status);
-      }
-    } catch (error) {
-      console.warn("[CallForge] Failed to patch session:", error);
-    }
-  }
   /**
    * Capture the GA4 client ID using gtag callback.
    * Only runs if ga4MeasurementId is configured.
@@ -244,26 +248,20 @@ var CallForge = class _CallForge {
         const autoParams2 = this.getAutoParams();
         const params2 = __spreadValues(__spreadValues(__spreadValues({}, autoParams2), dataWithExtras.params), this.customParams);
         this.saveToCache(effectiveLocId, data2, params2);
-        this.sessionId = data2.sessionId;
-        this.sessionCreated = true;
         return this.formatApiResponse(data2);
       } catch (e) {
       }
     }
     const cached = this.cache.get(locationId);
     if (cached) {
-      this.sessionId = cached.sessionId;
-      this.sessionCreated = true;
       return this.formatSession(cached);
     }
     const autoParams = this.getAutoParams();
     const cachedParams = this.cache.getParams();
     const params = __spreadValues(__spreadValues(__spreadValues({}, autoParams), cachedParams), this.customParams);
-    const cachedSessionId = this.cache.getSessionId(locationId);
-    const data = await this.fetchFromApi(locationId, cachedSessionId, params);
+    const cachedSessionToken = this.cache.getSessionToken(locationId);
+    const data = await this.fetchFromApi(locationId, cachedSessionToken, params);
     this.saveToCache(locationId, data, params);
-    this.sessionId = data.sessionId;
-    this.sessionCreated = true;
     return this.formatApiResponse(data);
   }
   getLocationId() {
@@ -283,8 +281,8 @@ var CallForge = class _CallForge {
     }
     return params;
   }
-  async fetchFromApi(locationId, sessionId, params) {
-    const url = this.buildUrl(locationId, sessionId, 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 {
@@ -303,29 +301,33 @@ var CallForge = class _CallForge {
   saveToCache(locationId, data, params) {
     const cached = {
       locId: locationId != null ? locationId : null,
-      sessionId: data.sessionId,
+      sessionToken: data.sessionToken,
+      leaseId: data.leaseId,
       phoneNumber: data.phoneNumber,
       location: data.location,
       expiresAt: data.expiresAt,
+      tokenVersion: "v1",
       params
     };
     this.cache.set(cached);
   }
   formatSession(cached) {
     return {
-      sessionId: cached.sessionId,
+      sessionToken: cached.sessionToken,
+      leaseId: cached.leaseId,
       phoneNumber: cached.phoneNumber,
       location: cached.location
     };
   }
   formatApiResponse(data) {
     return {
-      sessionId: data.sessionId,
+      sessionToken: data.sessionToken,
+      leaseId: data.leaseId,
       phoneNumber: data.phoneNumber,
       location: data.location
     };
   }
-  buildUrl(locationId, sessionId, params) {
+  buildUrl(locationId, sessionToken, params) {
     const { categoryId, endpoint } = this.config;
     const queryParams = {
       categoryId
@@ -333,8 +335,8 @@ var CallForge = class _CallForge {
     if (locationId) {
       queryParams.loc_physical_ms = locationId;
     }
-    if (sessionId) {
-      queryParams.sessionId = sessionId;
+    if (sessionToken) {
+      queryParams.sessionToken = sessionToken;
     }
     for (const [key, value] of Object.entries(params)) {
       if (value !== void 0) {
@@ -364,29 +366,29 @@ function getPreloadSnippet(config) {
       `Invalid endpoint: "${endpoint}". Must be a valid HTTPS URL`
     );
   }
-  const cacheKey = `cf_tracking_${categoryId}`;
   const script = `(function(){
 var u=new URLSearchParams(location.search);
 var loc=u.get('loc_physical_ms');
 var ap=['gclid','gbraid','wbraid','msclkid','fbclid','gad_campaignid','gad_source'];
 var p={};
 for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
-var key='${cacheKey}';
-var sid=null;
+var site='${config.siteKey || ""}'||location.hostname||'unknown-site';
+var key='cf_tracking_v1_'+site+'_${categoryId}';
+var token=null;
 try{
 var c=JSON.parse(localStorage.getItem(key));
 if(c&&c.expiresAt>Date.now()+30000){
 if(!loc||(loc&&c.locId===loc)){c.params=Object.assign({},c.params,p);window.__cfTracking=Promise.resolve(c);return}
-sid=(c.locId===loc)?c.sessionId:null;
+token=(!loc||c.locId===loc)?c.sessionToken:null;
 var cp=c.params||{};
 p=Object.assign({},cp,p);
 }}catch(e){}
 var url='${endpoint}/v1/tracking/session?categoryId=${categoryId}';
 if(loc)url+='&loc_physical_ms='+loc;
-if(sid)url+='&sessionId='+sid;
+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){return r.json()}).then(function(d){d.params=p;try{localStorage.setItem(key,JSON.stringify({locId:loc,sessionId:d.sessionId,phoneNumber:d.phoneNumber,location:d.location,expiresAt:d.expiresAt,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,location:d.location,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

@@ -18,10 +18,11 @@ var __spreadValues = (a, b) => {
 // src/cache.ts
 var EXPIRY_BUFFER_MS = 3e4;
 var TrackingCache = class {
-  constructor(categoryId) {
+  constructor(categoryId, siteKey) {
     this.memoryCache = null;
     this.useMemory = false;
-    this.key = `cf_tracking_${categoryId}`;
+    const resolvedSiteKey = siteKey || (typeof window !== "undefined" ? window.location.hostname : "unknown-site");
+    this.key = `cf_tracking_v1_${resolvedSiteKey}_${categoryId}`;
     this.useMemory = !this.isLocalStorageAvailable();
   }
   isLocalStorageAvailable() {
@@ -54,17 +55,15 @@ var TrackingCache = class {
     return cached;
   }
   /**
-   * Get sessionId for refresh if location matches (regardless of expiry).
-   * Used when cache is expired but location is same - send sessionId to server.
-   *
-   * Only returns sessionId if locationId is provided AND matches cached locId.
-   * (IP-based sessions don't send sessionId for refresh since location may differ)
+   * Get sessionToken for refresh if location matches (regardless of expiry).
+   * Used when cache is expired but location is same - send token to server.
    */
-  getSessionId(locationId) {
+  getSessionToken(locationId) {
     const cached = this.read();
     if (!cached) return null;
-    if (!locationId || cached.locId !== locationId) return null;
-    return cached.sessionId;
+    if (!locationId) return cached.sessionToken;
+    if (cached.locId !== locationId) return null;
+    return cached.sessionToken;
   }
   /**
    * Get cached params (for merging with new params).
@@ -118,19 +117,19 @@ var TrackingCache = class {
 // src/client.ts
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 var FETCH_TIMEOUT_MS = 1e4;
+var CALL_INTENT_TIMEOUT_MS = 8e3;
 var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campaignid", "gad_source"];
 var CallForge = class _CallForge {
   constructor(config) {
     this.sessionPromise = null;
     this.customParams = {};
-    this.sessionId = null;
-    this.sessionCreated = false;
     this.config = {
       categoryId: config.categoryId,
       endpoint: config.endpoint || DEFAULT_ENDPOINT,
-      ga4MeasurementId: config.ga4MeasurementId
+      ga4MeasurementId: config.ga4MeasurementId,
+      siteKey: config.siteKey
     };
-    this.cache = new TrackingCache(config.categoryId);
+    this.cache = new TrackingCache(config.categoryId, config.siteKey);
     this.captureGA4ClientId();
   }
   /**
@@ -150,6 +149,33 @@ var CallForge = class _CallForge {
     this.sessionPromise = this.fetchSession();
     return this.sessionPromise;
   }
+  /**
+   * Create a short-lived call intent token for click/callback deterministic attribution.
+   */
+  async createCallIntent() {
+    const session = await this.getSession();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), CALL_INTENT_TIMEOUT_MS);
+    try {
+      const response = await fetch(`${this.config.endpoint}/v1/tracking/call-intent`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        credentials: "omit",
+        signal: controller.signal,
+        body: JSON.stringify({
+          sessionToken: session.sessionToken
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`Call intent API error: ${response.status} ${response.statusText}`);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * Subscribe to session ready event.
    * Callback is called once session data is available.
@@ -159,15 +185,10 @@ var CallForge = class _CallForge {
     });
   }
   /**
-   * Set custom tracking parameters.
-   * If session already exists, sends PATCH to update.
-   * Otherwise queues params for next session request.
+   * Set custom tracking parameters for the next session fetch.
    */
   async setParams(params) {
     this.customParams = __spreadValues(__spreadValues({}, this.customParams), params);
-    if (this.sessionCreated && this.sessionId) {
-      await this.patchSession(params);
-    }
   }
   /**
    * Get the currently queued custom params.
@@ -175,23 +196,6 @@ var CallForge = class _CallForge {
   getQueuedParams() {
     return __spreadValues({}, this.customParams);
   }
-  async patchSession(params) {
-    try {
-      const response = await fetch(
-        `${this.config.endpoint}/v1/tracking/session/${this.sessionId}`,
-        {
-          method: "PATCH",
-          headers: { "Content-Type": "application/json" },
-          body: JSON.stringify(params)
-        }
-      );
-      if (!response.ok) {
-        console.warn("[CallForge] Failed to patch session:", response.status);
-      }
-    } catch (error) {
-      console.warn("[CallForge] Failed to patch session:", error);
-    }
-  }
   /**
    * Capture the GA4 client ID using gtag callback.
    * Only runs if ga4MeasurementId is configured.
@@ -220,26 +224,20 @@ var CallForge = class _CallForge {
         const autoParams2 = this.getAutoParams();
         const params2 = __spreadValues(__spreadValues(__spreadValues({}, autoParams2), dataWithExtras.params), this.customParams);
         this.saveToCache(effectiveLocId, data2, params2);
-        this.sessionId = data2.sessionId;
-        this.sessionCreated = true;
         return this.formatApiResponse(data2);
       } catch (e) {
       }
     }
     const cached = this.cache.get(locationId);
     if (cached) {
-      this.sessionId = cached.sessionId;
-      this.sessionCreated = true;
       return this.formatSession(cached);
     }
     const autoParams = this.getAutoParams();
     const cachedParams = this.cache.getParams();
     const params = __spreadValues(__spreadValues(__spreadValues({}, autoParams), cachedParams), this.customParams);
-    const cachedSessionId = this.cache.getSessionId(locationId);
-    const data = await this.fetchFromApi(locationId, cachedSessionId, params);
+    const cachedSessionToken = this.cache.getSessionToken(locationId);
+    const data = await this.fetchFromApi(locationId, cachedSessionToken, params);
     this.saveToCache(locationId, data, params);
-    this.sessionId = data.sessionId;
-    this.sessionCreated = true;
     return this.formatApiResponse(data);
   }
   getLocationId() {
@@ -259,8 +257,8 @@ var CallForge = class _CallForge {
     }
     return params;
   }
-  async fetchFromApi(locationId, sessionId, params) {
-    const url = this.buildUrl(locationId, sessionId, 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 {
@@ -279,29 +277,33 @@ var CallForge = class _CallForge {
   saveToCache(locationId, data, params) {
     const cached = {
       locId: locationId != null ? locationId : null,
-      sessionId: data.sessionId,
+      sessionToken: data.sessionToken,
+      leaseId: data.leaseId,
       phoneNumber: data.phoneNumber,
       location: data.location,
       expiresAt: data.expiresAt,
+      tokenVersion: "v1",
       params
     };
     this.cache.set(cached);
   }
   formatSession(cached) {
     return {
-      sessionId: cached.sessionId,
+      sessionToken: cached.sessionToken,
+      leaseId: cached.leaseId,
       phoneNumber: cached.phoneNumber,
       location: cached.location
     };
   }
   formatApiResponse(data) {
     return {
-      sessionId: data.sessionId,
+      sessionToken: data.sessionToken,
+      leaseId: data.leaseId,
       phoneNumber: data.phoneNumber,
       location: data.location
     };
   }
-  buildUrl(locationId, sessionId, params) {
+  buildUrl(locationId, sessionToken, params) {
     const { categoryId, endpoint } = this.config;
     const queryParams = {
       categoryId
@@ -309,8 +311,8 @@ var CallForge = class _CallForge {
     if (locationId) {
       queryParams.loc_physical_ms = locationId;
     }
-    if (sessionId) {
-      queryParams.sessionId = sessionId;
+    if (sessionToken) {
+      queryParams.sessionToken = sessionToken;
     }
     for (const [key, value] of Object.entries(params)) {
       if (value !== void 0) {
@@ -340,29 +342,29 @@ function getPreloadSnippet(config) {
       `Invalid endpoint: "${endpoint}". Must be a valid HTTPS URL`
     );
   }
-  const cacheKey = `cf_tracking_${categoryId}`;
   const script = `(function(){
 var u=new URLSearchParams(location.search);
 var loc=u.get('loc_physical_ms');
 var ap=['gclid','gbraid','wbraid','msclkid','fbclid','gad_campaignid','gad_source'];
 var p={};
 for(var i=0;i<ap.length;i++){var v=u.get(ap[i]);if(v)p[ap[i]]=v}
-var key='${cacheKey}';
-var sid=null;
+var site='${config.siteKey || ""}'||location.hostname||'unknown-site';
+var key='cf_tracking_v1_'+site+'_${categoryId}';
+var token=null;
 try{
 var c=JSON.parse(localStorage.getItem(key));
 if(c&&c.expiresAt>Date.now()+30000){
 if(!loc||(loc&&c.locId===loc)){c.params=Object.assign({},c.params,p);window.__cfTracking=Promise.resolve(c);return}
-sid=(c.locId===loc)?c.sessionId:null;
+token=(!loc||c.locId===loc)?c.sessionToken:null;
 var cp=c.params||{};
 p=Object.assign({},cp,p);
 }}catch(e){}
 var url='${endpoint}/v1/tracking/session?categoryId=${categoryId}';
 if(loc)url+='&loc_physical_ms='+loc;
-if(sid)url+='&sessionId='+sid;
+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){return r.json()}).then(function(d){d.params=p;try{localStorage.setItem(key,JSON.stringify({locId:loc,sessionId:d.sessionId,phoneNumber:d.phoneNumber,location:d.location,expiresAt:d.expiresAt,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,location:d.location,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,30 +1,33 @@
 {
   "name": "@callforge/tracking-client",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "main": "dist/index.js",
-  "module": "dist/index.js",
+  "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
     }
   },
+  "publishConfig": {
+    "access": "public"
+  },
   "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"
   }
-}
+}