@callforge/tracking-client 0.6.0 → 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.6.0** - Adds `createCallIntent()` helper for click/callback deterministic attribution and fixes ESM/CJS exports.
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@callforge/tracking-client",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",