@formo/analytics 1.28.6 → 1.29.1

package/dist/esm/src/event/EventFactory.js

@@ -54,9 +54,10 @@ import { logger } from "../logger";
 import mergeDeepRight from "../ramda/mergeDeepRight";
 import { session } from "../storage";
 import { version } from "../version";
-import { CHANNEL, VERSION, PAGE_PROPERTIES_EXCLUDED_FIELDS } from "./constants";
+import { CHANNEL, CLICK_ID_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS, VERSION, } from "./constants";
 import { generateAnonymousId } from "./utils";
 import { detectBrowser } from "../browser/browsers";
+var ISO_3166_ALPHA_2_REGEX = /^[A-Z]{2}$/;
 var EventFactory = /** @class */ (function () {
     function EventFactory(options) {
         var _this = this;
@@ -81,6 +82,15 @@ var EventFactory = /** @class */ (function () {
             catch (_a) { }
             return result;
         };
+        this.extractClickIdParameters = function (urlObj) {
+            var result = {};
+            for (var _i = 0, CLICK_ID_PARAMS_1 = CLICK_ID_PARAMS; _i < CLICK_ID_PARAMS_1.length; _i++) {
+                var param = CLICK_ID_PARAMS_1[_i];
+                var value = urlObj.searchParams.get(param);
+                result[param] = value ? value.trim() : "";
+            }
+            return result;
+        };
         this.extractReferralParameter = function (urlObj) {
             var _a, _b, _c;
             // Strategy: Check query params first, then check path pattern if configured
@@ -113,25 +123,23 @@ var EventFactory = /** @class */ (function () {
         };
         this.getTrafficSources = function (url) {
             var urlObj = new URL(url);
-            var contextTrafficSources = __assign(__assign({}, _this.extractUTMParameters(url)), { ref: _this.extractReferralParameter(urlObj), referrer: document.referrer });
+            var contextTrafficSources = __assign(__assign(__assign({}, _this.extractUTMParameters(url)), _this.extractClickIdParameters(urlObj)), { ref: _this.extractReferralParameter(urlObj), referrer: document.referrer });
             var storedTrafficSources = session().get(SESSION_TRAFFIC_SOURCE_KEY) || {};
-            var finalTrafficSources = {
-                ref: contextTrafficSources.ref || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.ref) || "",
-                referrer: contextTrafficSources.referrer || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.referrer) || "",
-                utm_campaign: contextTrafficSources.utm_campaign ||
+            var mergedClickIds = {};
+            for (var _i = 0, CLICK_ID_PARAMS_2 = CLICK_ID_PARAMS; _i < CLICK_ID_PARAMS_2.length; _i++) {
+                var p = CLICK_ID_PARAMS_2[_i];
+                mergedClickIds[p] =
+                    contextTrafficSources[p] || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources[p]) || "";
+            }
+            var finalTrafficSources = __assign({ ref: contextTrafficSources.ref || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.ref) || "", referrer: contextTrafficSources.referrer || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.referrer) || "", utm_campaign: contextTrafficSources.utm_campaign ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_campaign) ||
-                    "",
-                utm_content: contextTrafficSources.utm_content ||
+                    "", utm_content: contextTrafficSources.utm_content ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_content) ||
-                    "",
-                utm_medium: contextTrafficSources.utm_medium ||
+                    "", utm_medium: contextTrafficSources.utm_medium ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_medium) ||
-                    "",
-                utm_source: contextTrafficSources.utm_source ||
+                    "", utm_source: contextTrafficSources.utm_source ||
                     (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_source) ||
-                    "",
-                utm_term: contextTrafficSources.utm_term || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_term) || "",
-            };
+                    "", utm_term: contextTrafficSources.utm_term || (storedTrafficSources === null || storedTrafficSources === void 0 ? void 0 : storedTrafficSources.utm_term) || "" }, mergedClickIds);
             // Store to session
             var sessionStoredTrafficSources = Object.keys(finalTrafficSources).reduce(function (res, key) {
                 var value = finalTrafficSources[key];
@@ -217,9 +225,14 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.getLocation = function () {
         try {
             var timezone = this.getTimezone();
-            if (timezone in COUNTRY_LIST)
-                return COUNTRY_LIST[timezone];
-            return timezone;
+            if (!timezone)
+                return "";
+            var mapped = COUNTRY_LIST[timezone];
+            // Only emit ISO-3166 alpha-2. Anything else (including the raw
+            // timezone string) is treated as unknown.
+            return typeof mapped === "string" && ISO_3166_ALPHA_2_REGEX.test(mapped)
+                ? mapped
+                : "";
         }
         catch (error) {
             logger.error("Error resolving location:", error);

package/dist/esm/src/event/constants.d.ts

@@ -1,11 +1,17 @@
 declare const CHANNEL = "web";
 declare const VERSION = "0";
+/**
+ * Paid-attribution click IDs captured from the landing-page URL and persisted
+ * across the session alongside UTM parameters. Keep the ClickIdParameters type
+ * in src/types/events.ts derived from this array.
+ */
+declare const CLICK_ID_PARAMS: readonly ["gclid", "gad_source", "fbclid", "msclkid", "twclid", "li_fat_id", "rdt_cid", "ttclid"];
 /**
  * Fields that should be excluded from page event properties parsing
  * These are either:
- * - Already captured in event context (UTM params, referral params)
+ * - Already captured in event context (UTM params, referral params, click IDs)
  * - Semantic event properties that should not be overridden by URL params
  */
 declare const PAGE_PROPERTIES_EXCLUDED_FIELDS: Set<string>;
-export { CHANNEL, VERSION, PAGE_PROPERTIES_EXCLUDED_FIELDS };
+export { CHANNEL, VERSION, CLICK_ID_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS };
 //# sourceMappingURL=constants.d.ts.map

package/dist/esm/src/event/constants.js

@@ -1,12 +1,36 @@
+var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
+    if (pack || arguments.length === 2) for (var i = 0, l = from.length, ar; i < l; i++) {
+        if (ar || !(i in from)) {
+            if (!ar) ar = Array.prototype.slice.call(from, 0, i);
+            ar[i] = from[i];
+        }
+    }
+    return to.concat(ar || Array.prototype.slice.call(from));
+};
 var CHANNEL = "web";
 var VERSION = "0";
+/**
+ * Paid-attribution click IDs captured from the landing-page URL and persisted
+ * across the session alongside UTM parameters. Keep the ClickIdParameters type
+ * in src/types/events.ts derived from this array.
+ */
+var CLICK_ID_PARAMS = [
+    "gclid", // Google Ads
+    "gad_source", // Google Ads (newer)
+    "fbclid", // Meta (Facebook/Instagram)
+    "msclkid", // Microsoft Ads (Bing)
+    "twclid", // Twitter/X Ads
+    "li_fat_id", // LinkedIn Ads
+    "rdt_cid", // Reddit Ads
+    "ttclid", // TikTok Ads
+];
 /**
  * Fields that should be excluded from page event properties parsing
  * These are either:
- * - Already captured in event context (UTM params, referral params)
+ * - Already captured in event context (UTM params, referral params, click IDs)
  * - Semantic event properties that should not be overridden by URL params
  */
-var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set([
+var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set(__spreadArray(__spreadArray([
     // Context fields (already captured in event context)
     'utm_source',
     'utm_medium',
@@ -16,7 +40,8 @@ var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set([
     'ref',
     'referral',
     'refcode',
-    'referrer',
+    'referrer'
+], CLICK_ID_PARAMS, true), [
     // Semantic event properties (should not be overridden by URL params)
     'category',
     'name',
@@ -24,6 +49,6 @@ var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set([
     'path',
     'hash',
     'query',
-]);
-export { CHANNEL, VERSION, PAGE_PROPERTIES_EXCLUDED_FIELDS };
+], false));
+export { CHANNEL, VERSION, CLICK_ID_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS };
 //# sourceMappingURL=constants.js.map

package/dist/esm/src/types/events.d.ts

@@ -1,6 +1,7 @@
 import { UUID } from "crypto";
 import { Address, ChainID, Nullable } from "./base";
 import { TEventChannel, TEventType } from "../constants";
+import { CLICK_ID_PARAMS } from "../event/constants";
 export type AnonymousID = UUID;
 export interface ICommonProperties {
     anonymous_id: AnonymousID;
@@ -21,7 +22,10 @@ export type UTMParameters = {
     utm_term: string;
     utm_content: string;
 };
-export type ITrafficSource = UTMParameters & {
+export type ClickIdParameters = {
+    [K in (typeof CLICK_ID_PARAMS)[number]]: string;
+};
+export type ITrafficSource = UTMParameters & ClickIdParameters & {
     ref: string;
     referrer: string;
 };

package/dist/esm/src/version.d.ts

@@ -1,2 +1,2 @@
-export declare const version = "1.28.6";
+export declare const version = "1.29.1";
 //# sourceMappingURL=version.d.ts.map

package/dist/esm/src/version.js

@@ -1,4 +1,4 @@
 // This file is auto-generated by scripts/update-version.js during npm version
 // Do not edit manually - it will be overwritten
-export var version = '1.28.6';
+export var version = '1.29.1';
 //# sourceMappingURL=version.js.map