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

@callforge/tracking-client 0.8.0 → 0.9.1

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

@@ -19,6 +19,19 @@ Client integration requirements:
 - 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.
+## Realtime Data Layer Upgrade (v0.9+)
+This release adds explicit browser helpers for the new realtime layer:
+- `client.linkPhoneCall({ phoneNumber })` for strict web-click to phone-call linkage.
+- `client.setWebZip(zipCode, { source })` for immediate web ZIP availability to call processing.
+Integration checklist:
+- Call `linkPhoneCall` immediately before opening a `tel:` link.
+- Pass the exact dialed number string (`+1...`) used by the link.
+- Continue dialing even if `linkPhoneCall` fails (best-effort attribution assist, not UX-blocking).
+- Call `setWebZip` when the visitor selects or types a ZIP.
+- Keep `setParams` for broader attribution params; use `setWebZip` for fast ZIP propagation.
 ## Quick Start
 ### 1. Add preload snippet to `<head>` (required for deterministic leases)
@@ -84,7 +97,34 @@ Notes:
 - `callIntentToken` is short-lived and single-use.
 - Treat it as an opaque secret (do not log it).
-### 4. GA4 Integration
+### 4. Realtime call-link + web ZIP helpers (recommended)
+Use explicit helpers to write realtime data from the browser.
+```typescript
+const client = CallForge.init({ categoryId: 'your-category-id' });
+async function dialTrackedNumber(phoneNumber: string) {
+  try {
+    // Default TTL is 30s (clamped server-side to 5-120s).
+    await client.linkPhoneCall({ phoneNumber });
+  } finally {
+    // Do not block dialing on telemetry failure.
+    window.location.href = `tel:${phoneNumber}`;
+  }
+}
+// Example ZIP picker handler
+await client.setWebZip('30309', { source: 'manual' });
+```
+Notes:
+- `linkPhoneCall` is optimized for mobile tap-to-call timing.
+- `setWebZip` accepts `manual` (typed) and `suggested` (picked from options).
+- `setWebZip` validates ZIP format (`12345`) client-side before sending.
+- `setWebZip` also sends `webZip` as a custom session param in a best-effort sync backup path.
+### 5. GA4 Integration
 To enable GA4 call event tracking, CallForge needs the GA4 `client_id` for the visitor (from the `_ga` cookie).
 Optionally provide your GA4 Measurement ID to improve client ID capture reliability when Google Analytics loads late.
@@ -114,7 +154,7 @@ client.setParams({
 });
 ```
-### 5. Track conversion parameters (optional)
+### 6. Track conversion parameters (optional)
 The client automatically captures ad platform click IDs from the URL:
@@ -214,6 +254,41 @@ const intent = await client.createCallIntent();
 console.log(intent.callIntentToken);
 ```
+### `client.linkPhoneCall(input)`
+Create a short-lived realtime call-link intent keyed by dialed number.
+```typescript
+const result = await client.linkPhoneCall({
+  phoneNumber: '+13105551234',
+  ttlSeconds: 30, // Optional, default 30s
+});
+console.log(result.status); // 'ready'
+```
+Use this right before `tel:` navigation so inbound call handling can perform strict 1:1 consume.
+### `client.setWebZip(zipCode, options?)`
+Store visitor-selected ZIP in the realtime profile layer for immediate call-side enrichment.
+```typescript
+const result = await client.setWebZip('30309', {
+  source: 'manual', // or 'suggested'
+  ttlSeconds: 3600, // Optional
+});
+if (result.status === 'ready') {
+  console.log(result.profile.webZipCode);
+}
+```
+Behavior:
+- Rejects invalid ZIP values unless they are 5 digits.
+- Writes profile data keyed by `sessionId`.
+- Also mirrors `webZip` and `webZipSource` into custom params and triggers a best-effort session sync backup.
 ### `client.onReady(callback)`
 Subscribe to session ready event. Callback is called once session data is available.
@@ -325,6 +400,9 @@ import type {
   ReadyCallback,
   LocationReadyCallback,
   CallIntentResponse,
+  CallLinkIntentResponse,
+  RealtimeProfileResponse,
+  RealtimeProfileSource,
 } from '@callforge/tracking-client';
 ```

package/dist/index.d.mts CHANGED Viewed

@@ -83,6 +83,27 @@ interface CallIntentResponse {
     expiresAt: string;
     attributionVersion: 'v1';
 }
+interface CallLinkIntentResponse {
+    status: 'ready';
+    intentId: string;
+    sessionId: string;
+    categoryId: string;
+    phoneNumber: string;
+    expiresAt: string;
+}
+type RealtimeProfileSource = 'manual' | 'suggested';
+type RealtimeProfileResponse = {
+    status: 'ready';
+    profile: {
+        sessionId: string;
+        webZipCode: string;
+        webZipSource: RealtimeProfileSource;
+        webZipUpdatedAt: string;
+        expiresAt: string;
+    };
+} | {
+    status: 'unavailable';
+};
 /**
  * Callback function for onReady subscription.
  */
@@ -135,6 +156,21 @@ declare class CallForge {
      * Create a short-lived call intent token for click/callback deterministic attribution.
      */
     createCallIntent(): Promise<CallIntentResponse>;
+    /**
+     * Create a short-lived realtime call-link intent for a specific dialed number.
+     * Use this immediately before opening a `tel:` link.
+     */
+    linkPhoneCall(input: {
+        phoneNumber: string;
+        ttlSeconds?: number;
+    }): Promise<CallLinkIntentResponse>;
+    /**
+     * Write visitor-selected web ZIP to the realtime data layer.
+     */
+    setWebZip(zipCode: string, options?: {
+        source?: RealtimeProfileSource;
+        ttlSeconds?: number;
+    }): Promise<RealtimeProfileResponse>;
     /**
      * Subscribe to session ready event.
      * Callback is called once session data is available.
@@ -198,4 +234,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
-export { CallForge, type CallForgeConfig, type CallIntentResponse, type LocationReadyCallback, type ReadyCallback, type TrackingLocation, type TrackingLocationSource, type TrackingParams, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type CallIntentResponse, type CallLinkIntentResponse, type LocationReadyCallback, type ReadyCallback, type RealtimeProfileResponse, type RealtimeProfileSource, type TrackingLocation, type TrackingLocationSource, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.d.ts CHANGED Viewed

@@ -83,6 +83,27 @@ interface CallIntentResponse {
     expiresAt: string;
     attributionVersion: 'v1';
 }
+interface CallLinkIntentResponse {
+    status: 'ready';
+    intentId: string;
+    sessionId: string;
+    categoryId: string;
+    phoneNumber: string;
+    expiresAt: string;
+}
+type RealtimeProfileSource = 'manual' | 'suggested';
+type RealtimeProfileResponse = {
+    status: 'ready';
+    profile: {
+        sessionId: string;
+        webZipCode: string;
+        webZipSource: RealtimeProfileSource;
+        webZipUpdatedAt: string;
+        expiresAt: string;
+    };
+} | {
+    status: 'unavailable';
+};
 /**
  * Callback function for onReady subscription.
  */
@@ -135,6 +156,21 @@ declare class CallForge {
      * Create a short-lived call intent token for click/callback deterministic attribution.
      */
     createCallIntent(): Promise<CallIntentResponse>;
+    /**
+     * Create a short-lived realtime call-link intent for a specific dialed number.
+     * Use this immediately before opening a `tel:` link.
+     */
+    linkPhoneCall(input: {
+        phoneNumber: string;
+        ttlSeconds?: number;
+    }): Promise<CallLinkIntentResponse>;
+    /**
+     * Write visitor-selected web ZIP to the realtime data layer.
+     */
+    setWebZip(zipCode: string, options?: {
+        source?: RealtimeProfileSource;
+        ttlSeconds?: number;
+    }): Promise<RealtimeProfileResponse>;
     /**
      * Subscribe to session ready event.
      * Callback is called once session data is available.
@@ -198,4 +234,4 @@ declare class CallForge {
  */
 declare function getPreloadSnippet(config: CallForgeConfig): string;
-export { CallForge, type CallForgeConfig, type CallIntentResponse, type LocationReadyCallback, type ReadyCallback, type TrackingLocation, type TrackingLocationSource, type TrackingParams, type TrackingSession, getPreloadSnippet };
+export { CallForge, type CallForgeConfig, type CallIntentResponse, type CallLinkIntentResponse, type LocationReadyCallback, type ReadyCallback, type RealtimeProfileResponse, type RealtimeProfileSource, type TrackingLocation, type TrackingLocationSource, type TrackingParams, type TrackingSession, getPreloadSnippet };

package/dist/index.js CHANGED Viewed

@@ -1,6 +1,8 @@
 "use strict";
 var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
@@ -17,6 +19,7 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -203,8 +206,11 @@ var LocationCache = class {
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 var FETCH_TIMEOUT_MS = 1e4;
 var CALL_INTENT_TIMEOUT_MS = 8e3;
+var REALTIME_CALL_LINK_TIMEOUT_MS = 5e3;
+var REALTIME_PROFILE_TIMEOUT_MS = 5e3;
 var BOOTSTRAP_TOKEN_EXPIRY_BUFFER_MS = 1e4;
 var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campaignid", "gad_source"];
+var ZIP_CODE_PATTERN = /^\d{5}$/;
 var CallForge = class _CallForge {
   constructor(config) {
     this.bootstrapMemoryCache = null;
@@ -289,6 +295,83 @@ var CallForge = class _CallForge {
       clearTimeout(timeoutId);
     }
   }
+  /**
+   * Create a short-lived realtime call-link intent for a specific dialed number.
+   * Use this immediately before opening a `tel:` link.
+   */
+  async linkPhoneCall(input) {
+    const session = await this.getSession();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), REALTIME_CALL_LINK_TIMEOUT_MS);
+    try {
+      const response = await fetch(`${this.config.endpoint}/v1/tracking/call-link-intent`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        credentials: "omit",
+        signal: controller.signal,
+        body: JSON.stringify({
+          sessionToken: session.sessionToken,
+          phoneNumber: input.phoneNumber,
+          ttlSeconds: input.ttlSeconds
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`Realtime call-link API error: ${response.status} ${response.statusText}`);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Write visitor-selected web ZIP to the realtime data layer.
+   */
+  async setWebZip(zipCode, options) {
+    var _a;
+    const normalizedZip = zipCode.trim();
+    if (!ZIP_CODE_PATTERN.test(normalizedZip)) {
+      throw new Error("Invalid ZIP code. Expected a 5-digit ZIP.");
+    }
+    const session = await this.getSession();
+    const fallbackSource = (_a = options == null ? void 0 : options.source) != null ? _a : "manual";
+    void this.setParams({
+      webZip: normalizedZip,
+      webZipSource: fallbackSource
+    });
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), REALTIME_PROFILE_TIMEOUT_MS);
+    try {
+      const response = await fetch(`${this.config.endpoint}/v1/tracking/realtime-profile`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        credentials: "omit",
+        signal: controller.signal,
+        body: JSON.stringify({
+          sessionToken: session.sessionToken,
+          webZip: normalizedZip,
+          source: options == null ? void 0 : options.source,
+          ttlSeconds: options == null ? void 0 : options.ttlSeconds
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`Realtime profile API error: ${response.status} ${response.statusText}`);
+      }
+      const result = await response.json();
+      if (result.status === "ready") {
+        this.customParams = __spreadProps(__spreadValues({}, this.customParams), {
+          webZip: result.profile.webZipCode,
+          webZipSource: result.profile.webZipSource
+        });
+      }
+      return result;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * Subscribe to session ready event.
    * Callback is called once session data is available.

package/dist/index.mjs CHANGED Viewed

@@ -1,4 +1,6 @@
 var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
 var __getOwnPropSymbols = Object.getOwnPropertySymbols;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __propIsEnum = Object.prototype.propertyIsEnumerable;
@@ -14,6 +16,7 @@ var __spreadValues = (a, b) => {
     }
   return a;
 };
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
 // src/cache.ts
 var EXPIRY_BUFFER_MS = 3e4;
@@ -179,8 +182,11 @@ var LocationCache = class {
 var DEFAULT_ENDPOINT = "https://tracking.callforge.io";
 var FETCH_TIMEOUT_MS = 1e4;
 var CALL_INTENT_TIMEOUT_MS = 8e3;
+var REALTIME_CALL_LINK_TIMEOUT_MS = 5e3;
+var REALTIME_PROFILE_TIMEOUT_MS = 5e3;
 var BOOTSTRAP_TOKEN_EXPIRY_BUFFER_MS = 1e4;
 var AUTO_PARAMS = ["gclid", "gbraid", "wbraid", "msclkid", "fbclid", "gad_campaignid", "gad_source"];
+var ZIP_CODE_PATTERN = /^\d{5}$/;
 var CallForge = class _CallForge {
   constructor(config) {
     this.bootstrapMemoryCache = null;
@@ -265,6 +271,83 @@ var CallForge = class _CallForge {
       clearTimeout(timeoutId);
     }
   }
+  /**
+   * Create a short-lived realtime call-link intent for a specific dialed number.
+   * Use this immediately before opening a `tel:` link.
+   */
+  async linkPhoneCall(input) {
+    const session = await this.getSession();
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), REALTIME_CALL_LINK_TIMEOUT_MS);
+    try {
+      const response = await fetch(`${this.config.endpoint}/v1/tracking/call-link-intent`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        credentials: "omit",
+        signal: controller.signal,
+        body: JSON.stringify({
+          sessionToken: session.sessionToken,
+          phoneNumber: input.phoneNumber,
+          ttlSeconds: input.ttlSeconds
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`Realtime call-link API error: ${response.status} ${response.statusText}`);
+      }
+      return await response.json();
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Write visitor-selected web ZIP to the realtime data layer.
+   */
+  async setWebZip(zipCode, options) {
+    var _a;
+    const normalizedZip = zipCode.trim();
+    if (!ZIP_CODE_PATTERN.test(normalizedZip)) {
+      throw new Error("Invalid ZIP code. Expected a 5-digit ZIP.");
+    }
+    const session = await this.getSession();
+    const fallbackSource = (_a = options == null ? void 0 : options.source) != null ? _a : "manual";
+    void this.setParams({
+      webZip: normalizedZip,
+      webZipSource: fallbackSource
+    });
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), REALTIME_PROFILE_TIMEOUT_MS);
+    try {
+      const response = await fetch(`${this.config.endpoint}/v1/tracking/realtime-profile`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json"
+        },
+        credentials: "omit",
+        signal: controller.signal,
+        body: JSON.stringify({
+          sessionToken: session.sessionToken,
+          webZip: normalizedZip,
+          source: options == null ? void 0 : options.source,
+          ttlSeconds: options == null ? void 0 : options.ttlSeconds
+        })
+      });
+      if (!response.ok) {
+        throw new Error(`Realtime profile API error: ${response.status} ${response.statusText}`);
+      }
+      const result = await response.json();
+      if (result.status === "ready") {
+        this.customParams = __spreadProps(__spreadValues({}, this.customParams), {
+          webZip: result.profile.webZipCode,
+          webZipSource: result.profile.webZipSource
+        });
+      }
+      return result;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   /**
    * Subscribe to session ready event.
    * Callback is called once session data is available.

package/package.json CHANGED Viewed

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