@formo/analytics 1.23.0 → 1.25.0

package/README.md

@@ -17,7 +17,7 @@
 
 ## Installation
 
-The Formo Web SDK is a Javascript library that allows you to track and analyze user interactions on your dapp. 
+The Formo Web SDK is a Javascript library that allows you to track user event data from your website and app. 
 
 You can install Formo on:
 - [Websites](https://docs.formo.so/install#website)

package/dist/cjs/src/FormoAnalytics.js

@@ -126,7 +126,7 @@ var FormoAnalytics = /** @class */ (function () {
             retryCount: options.retryCount,
             maxQueueSize: options.maxQueueSize,
             flushInterval: options.flushInterval,
-        }));
+        }), options);
         // Check consent status on initialization
         if (this.hasOptedOutTracking()) {
             lib_1.logger.info("User has previously opted out of tracking");

package/dist/cjs/src/lib/event/EventFactory.d.ts

@@ -1,6 +1,9 @@
-import { Address, APIEvent, ChainID, IFormoEvent, IFormoEventContext, IFormoEventProperties, Nullable, SignatureStatus, TransactionStatus } from "../../types";
+import { Address, APIEvent, ChainID, IFormoEvent, IFormoEventContext, IFormoEventProperties, Nullable, Options, SignatureStatus, TransactionStatus } from "../../types";
 import { IEventFactory } from "./type";
 declare class EventFactory implements IEventFactory {
+    private options?;
+    private compiledPathPattern?;
+    constructor(options?: Options);
     private getTimezone;
     private getLocation;
     private getLanguage;
@@ -8,6 +11,7 @@ declare class EventFactory implements IEventFactory {
     private extractUTMParameters;
     private extractReferralParameter;
     private getTrafficSources;
+    private getScreen;
     private generateContext;
     /**
      * Add any missing default page properties using values from options and defaults

package/dist/cjs/src/lib/event/EventFactory.js

@@ -59,13 +59,14 @@ var validators_1 = require("../../validators");
 var logger_1 = require("../logger");
 var mergeDeepRight_1 = __importDefault(require("../ramda/mergeDeepRight"));
 var storage_1 = require("../storage");
-var version_1 = require("../version");
+var version_1 = require("../../version");
 var constants_2 = require("./constants");
 var utils_2 = require("./utils");
 var browsers_1 = require("../browser/browsers");
 var EventFactory = /** @class */ (function () {
-    function EventFactory() {
+    function EventFactory(options) {
         var _this = this;
+        var _a;
         this.extractUTMParameters = function (url) {
             var result = {
                 utm_campaign: "",
@@ -87,14 +88,33 @@ var EventFactory = /** @class */ (function () {
             return result;
         };
         this.extractReferralParameter = function (urlObj) {
-            var _a;
-            var referralParams = ["ref", "referral", "refcode"];
+            var _a, _b, _c;
+            // Strategy: Check query params first, then check path pattern if configured
+            // Query params logic:
+            // - If no referral config exists → use defaults
+            // - If referral config exists but queryParams is undefined → use defaults
+            // - If referral config exists with queryParams → use those
+            var defaultParams = ["ref", "referral", "refcode"];
+            var referralParams = !((_a = _this.options) === null || _a === void 0 ? void 0 : _a.referral)
+                ? defaultParams // No referral config at all → use defaults
+                : ((_b = _this.options.referral.queryParams) !== null && _b !== void 0 ? _b : defaultParams); // Has config → use queryParams or defaults
+            // Check query parameters (if any configured)
             for (var _i = 0, referralParams_1 = referralParams; _i < referralParams_1.length; _i++) {
                 var param = referralParams_1[_i];
-                var value = (_a = urlObj.searchParams.get(param)) === null || _a === void 0 ? void 0 : _a.trim();
+                var value = (_c = urlObj.searchParams.get(param)) === null || _c === void 0 ? void 0 : _c.trim();
                 if (value)
                     return value;
             }
+            // Check URL path pattern if configured
+            if (_this.compiledPathPattern) {
+                var pathname = urlObj.pathname;
+                var match = pathname.match(_this.compiledPathPattern);
+                if (match && match[1]) {
+                    var referralCode = match[1].trim();
+                    if (referralCode)
+                        return referralCode;
+                }
+            }
             return "";
         };
         this.getTrafficSources = function (url) {
@@ -136,7 +156,8 @@ var EventFactory = /** @class */ (function () {
          * @param options API options
          */
         this.getPageProperties = function (properties) {
-            var pageProps = properties;
+            // Create a copy to avoid mutating the original properties object
+            var pageProps = __assign({}, properties);
             if ((0, validators_1.isUndefined)(pageProps.url)) {
                 pageProps.url = new URL(globalThis.location.href).href;
             }
@@ -146,8 +167,36 @@ var EventFactory = /** @class */ (function () {
             if ((0, validators_1.isUndefined)(pageProps.hash)) {
                 pageProps.hash = globalThis.location.hash;
             }
+            // Add query string without the '?' prefix
+            if ((0, validators_1.isUndefined)(pageProps.query)) {
+                pageProps.query = globalThis.location.search.slice(1);
+            }
+            // Parse query parameters and add as individual properties (don't overwrite existing)
+            // Skip fields that are already captured in context or are semantic event properties
+            try {
+                var urlObj = new URL(globalThis.location.href);
+                urlObj.searchParams.forEach(function (value, key) {
+                    // Only add if the property doesn't already exist and is not excluded
+                    if ((0, validators_1.isUndefined)(pageProps[key]) && !constants_2.PAGE_PROPERTIES_EXCLUDED_FIELDS.has(key)) {
+                        pageProps[key] = value;
+                    }
+                });
+            }
+            catch (error) {
+                logger_1.logger.error("Error parsing query parameters for page properties:", error);
+            }
             return pageProps;
         };
+        this.options = options;
+        // Compile regex pattern once for better performance
+        if ((_a = options === null || options === void 0 ? void 0 : options.referral) === null || _a === void 0 ? void 0 : _a.pathPattern) {
+            try {
+                this.compiledPathPattern = new RegExp(options.referral.pathPattern);
+            }
+            catch (error) {
+                logger_1.logger.warn("Invalid referral path pattern: ".concat(options.referral.pathPattern, ". Error: ").concat(error));
+            }
+        }
     }
     EventFactory.prototype.getTimezone = function () {
         try {
@@ -184,22 +233,45 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.getLibraryVersion = function () {
         return version_1.version;
     };
+    // Get screen dimensions and pixel density
+    // Returns safe defaults if any error occurs to ensure event creation continues
+    EventFactory.prototype.getScreen = function () {
+        var _a, _b;
+        var safeDefaults = {
+            screen_width: 0,
+            screen_height: 0,
+            screen_density: 1,
+            viewport_width: 0,
+            viewport_height: 0,
+        };
+        try {
+            return {
+                screen_width: ((_a = globalThis.screen) === null || _a === void 0 ? void 0 : _a.width) || 0,
+                screen_height: ((_b = globalThis.screen) === null || _b === void 0 ? void 0 : _b.height) || 0,
+                screen_density: globalThis.devicePixelRatio || 1,
+                viewport_width: globalThis.innerWidth || 0,
+                viewport_height: globalThis.innerHeight || 0,
+            };
+        }
+        catch (error) {
+            logger_1.logger.error("Error resolving screen properties:", error);
+            return safeDefaults;
+        }
+    };
     // Contextual fields that are automatically collected and populated by the Formo SDK
     EventFactory.prototype.generateContext = function (context) {
         return __awaiter(this, void 0, void 0, function () {
-            var path, browserName, language, timezone, location, library_version, defaultContext, mergedContext;
+            var browserName, language, timezone, location, library_version, defaultContext, mergedContext;
             return __generator(this, function (_a) {
                 switch (_a.label) {
-                    case 0:
-                        path = globalThis.location.pathname;
-                        return [4 /*yield*/, (0, browsers_1.detectBrowser)()];
+                    case 0: return [4 /*yield*/, (0, browsers_1.detectBrowser)()];
                     case 1:
                         browserName = _a.sent();
                         language = this.getLanguage();
                         timezone = this.getTimezone();
                         location = this.getLocation();
                         library_version = this.getLibraryVersion();
-                        defaultContext = __assign(__assign({ user_agent: globalThis.navigator.userAgent, locale: language, timezone: timezone, location: location }, this.getTrafficSources(globalThis.location.href)), { page_path: path, page_title: document.title, page_url: globalThis.location.href, library_name: "Formo Web SDK", library_version: library_version, browser: browserName });
+                        defaultContext = __assign(__assign(__assign({ user_agent: globalThis.navigator.userAgent, locale: language, timezone: timezone, location: location }, this.getTrafficSources(globalThis.location.href)), { page_title: document.title, page_url: globalThis.location.href, library_name: "Formo Web SDK", library_version: library_version, browser: browserName }), this.getScreen());
                         mergedContext = (0, mergeDeepRight_1.default)(defaultContext, context || {});
                         return [2 /*return*/, mergedContext];
                 }
@@ -247,7 +319,7 @@ var EventFactory = /** @class */ (function () {
         return __awaiter(this, void 0, void 0, function () {
             var props, pageEvent;
             return __generator(this, function (_a) {
-                props = properties !== null && properties !== void 0 ? properties : {};
+                props = __assign({}, (properties !== null && properties !== void 0 ? properties : {}));
                 props.category = category;
                 props.name = name;
                 props = this.getPageProperties(props);

package/dist/cjs/src/lib/event/EventManager.d.ts

@@ -1,4 +1,4 @@
-import { Address, APIEvent } from "../../types";
+import { Address, APIEvent, Options } from "../../types";
 import { IEventQueue } from "../queue";
 import { IEventFactory, IEventManager } from "./type";
 /**
@@ -10,8 +10,9 @@ declare class EventManager implements IEventManager {
     /**
      *
      * @param eventQueue Event queue instance
+     * @param options Optional configuration (referral parsing, etc.)
      */
-    constructor(eventQueue: IEventQueue);
+    constructor(eventQueue: IEventQueue, options?: Options);
     /**
      * Consumes a new incoming event
      * @param event Incoming event data

package/dist/cjs/src/lib/event/EventManager.js

@@ -58,10 +58,11 @@ var EventManager = /** @class */ (function () {
     /**
      *
      * @param eventQueue Event queue instance
+     * @param options Optional configuration (referral parsing, etc.)
      */
-    function EventManager(eventQueue) {
+    function EventManager(eventQueue, options) {
         this.eventQueue = eventQueue;
-        this.eventFactory = new EventFactory_1.EventFactory();
+        this.eventFactory = new EventFactory_1.EventFactory(options);
     }
     /**
      * Consumes a new incoming event

package/dist/cjs/src/lib/event/constants.d.ts

@@ -1,4 +1,11 @@
 declare const CHANNEL = "web";
 declare const VERSION = "0";
-export { CHANNEL, VERSION };
+/**
+ * Fields that should be excluded from page event properties parsing
+ * These are either:
+ * - Already captured in event context (UTM params, referral params)
+ * - 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 };
 //# sourceMappingURL=constants.d.ts.map

package/dist/cjs/src/lib/event/constants.js

@@ -1,8 +1,34 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.VERSION = exports.CHANNEL = void 0;
+exports.PAGE_PROPERTIES_EXCLUDED_FIELDS = exports.VERSION = exports.CHANNEL = void 0;
 var CHANNEL = "web";
 exports.CHANNEL = CHANNEL;
 var VERSION = "0";
 exports.VERSION = VERSION;
+/**
+ * Fields that should be excluded from page event properties parsing
+ * These are either:
+ * - Already captured in event context (UTM params, referral params)
+ * - Semantic event properties that should not be overridden by URL params
+ */
+var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set([
+    // Context fields (already captured in event context)
+    'utm_source',
+    'utm_medium',
+    'utm_campaign',
+    'utm_term',
+    'utm_content',
+    'ref',
+    'referral',
+    'refcode',
+    'referrer',
+    // Semantic event properties (should not be overridden by URL params)
+    'category',
+    'name',
+    'url',
+    'path',
+    'hash',
+    'query',
+]);
+exports.PAGE_PROPERTIES_EXCLUDED_FIELDS = PAGE_PROPERTIES_EXCLUDED_FIELDS;
 //# sourceMappingURL=constants.js.map

package/dist/cjs/src/types/base.d.ts

@@ -94,6 +94,24 @@ export interface AutocaptureOptions {
      */
     chain?: boolean;
 }
+/**
+ * Configuration options for referral parameter parsing
+ */
+export interface ReferralOptions {
+    /**
+     * Custom query parameter names to check for referral codes
+     * @default ["ref", "referral", "refcode"]
+     * @example ["via", "referrer", "source"] - will check ?via=CODE, ?referrer=CODE, ?source=CODE
+     */
+    queryParams?: string[];
+    /**
+     * URL path pattern to extract referral code from
+     * Should be a regex string that matches the path segment containing the referral code
+     * The first capture group will be used as the referral code
+     * @example "/r/([^/]+)" - will extract "01K17FKB" from "https://glider.fi/r/01K17FKB"
+     */
+    pathPattern?: string;
+}
 export interface Options {
     provider?: EIP1193Provider;
     tracking?: boolean | TrackingOptions;
@@ -122,6 +140,12 @@ export interface Options {
         enabled?: boolean;
         levels?: LogLevel[];
     };
+    /**
+     * Configuration for referral parameter parsing from URLs
+     * Allows customizing how referral codes are detected from query parameters and URL paths
+     * @example { queryParams: ["via"], pathPattern: "/r/([^/]+)" }
+     */
+    referral?: ReferralOptions;
     ready?: (formo: IFormoAnalytics) => void;
 }
 export interface FormoAnalyticsProviderProps {

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

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

package/dist/cjs/src/version.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.version = void 0;
+// This file is auto-generated by scripts/update-version.js during npm version
+// Do not edit manually - it will be overwritten
+exports.version = '1.25.0';
+//# sourceMappingURL=version.js.map

package/dist/esm/src/FormoAnalytics.js

@@ -123,7 +123,7 @@ var FormoAnalytics = /** @class */ (function () {
             retryCount: options.retryCount,
             maxQueueSize: options.maxQueueSize,
             flushInterval: options.flushInterval,
-        }));
+        }), options);
         // Check consent status on initialization
         if (this.hasOptedOutTracking()) {
             logger.info("User has previously opted out of tracking");

package/dist/esm/src/lib/event/EventFactory.d.ts

@@ -1,6 +1,9 @@
-import { Address, APIEvent, ChainID, IFormoEvent, IFormoEventContext, IFormoEventProperties, Nullable, SignatureStatus, TransactionStatus } from "../../types";
+import { Address, APIEvent, ChainID, IFormoEvent, IFormoEventContext, IFormoEventProperties, Nullable, Options, SignatureStatus, TransactionStatus } from "../../types";
 import { IEventFactory } from "./type";
 declare class EventFactory implements IEventFactory {
+    private options?;
+    private compiledPathPattern?;
+    constructor(options?: Options);
     private getTimezone;
     private getLocation;
     private getLanguage;
@@ -8,6 +11,7 @@ declare class EventFactory implements IEventFactory {
     private extractUTMParameters;
     private extractReferralParameter;
     private getTrafficSources;
+    private getScreen;
     private generateContext;
     /**
      * Add any missing default page properties using values from options and defaults

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

@@ -53,13 +53,14 @@ import { isUndefined } from "../../validators";
 import { logger } from "../logger";
 import mergeDeepRight from "../ramda/mergeDeepRight";
 import { session } from "../storage";
-import { version } from "../version";
-import { CHANNEL, VERSION } from "./constants";
+import { version } from "../../version";
+import { CHANNEL, VERSION, PAGE_PROPERTIES_EXCLUDED_FIELDS } from "./constants";
 import { generateAnonymousId } from "./utils";
 import { detectBrowser } from "../browser/browsers";
 var EventFactory = /** @class */ (function () {
-    function EventFactory() {
+    function EventFactory(options) {
         var _this = this;
+        var _a;
         this.extractUTMParameters = function (url) {
             var result = {
                 utm_campaign: "",
@@ -81,14 +82,33 @@ var EventFactory = /** @class */ (function () {
             return result;
         };
         this.extractReferralParameter = function (urlObj) {
-            var _a;
-            var referralParams = ["ref", "referral", "refcode"];
+            var _a, _b, _c;
+            // Strategy: Check query params first, then check path pattern if configured
+            // Query params logic:
+            // - If no referral config exists → use defaults
+            // - If referral config exists but queryParams is undefined → use defaults
+            // - If referral config exists with queryParams → use those
+            var defaultParams = ["ref", "referral", "refcode"];
+            var referralParams = !((_a = _this.options) === null || _a === void 0 ? void 0 : _a.referral)
+                ? defaultParams // No referral config at all → use defaults
+                : ((_b = _this.options.referral.queryParams) !== null && _b !== void 0 ? _b : defaultParams); // Has config → use queryParams or defaults
+            // Check query parameters (if any configured)
             for (var _i = 0, referralParams_1 = referralParams; _i < referralParams_1.length; _i++) {
                 var param = referralParams_1[_i];
-                var value = (_a = urlObj.searchParams.get(param)) === null || _a === void 0 ? void 0 : _a.trim();
+                var value = (_c = urlObj.searchParams.get(param)) === null || _c === void 0 ? void 0 : _c.trim();
                 if (value)
                     return value;
             }
+            // Check URL path pattern if configured
+            if (_this.compiledPathPattern) {
+                var pathname = urlObj.pathname;
+                var match = pathname.match(_this.compiledPathPattern);
+                if (match && match[1]) {
+                    var referralCode = match[1].trim();
+                    if (referralCode)
+                        return referralCode;
+                }
+            }
             return "";
         };
         this.getTrafficSources = function (url) {
@@ -130,7 +150,8 @@ var EventFactory = /** @class */ (function () {
          * @param options API options
          */
         this.getPageProperties = function (properties) {
-            var pageProps = properties;
+            // Create a copy to avoid mutating the original properties object
+            var pageProps = __assign({}, properties);
             if (isUndefined(pageProps.url)) {
                 pageProps.url = new URL(globalThis.location.href).href;
             }
@@ -140,8 +161,36 @@ var EventFactory = /** @class */ (function () {
             if (isUndefined(pageProps.hash)) {
                 pageProps.hash = globalThis.location.hash;
             }
+            // Add query string without the '?' prefix
+            if (isUndefined(pageProps.query)) {
+                pageProps.query = globalThis.location.search.slice(1);
+            }
+            // Parse query parameters and add as individual properties (don't overwrite existing)
+            // Skip fields that are already captured in context or are semantic event properties
+            try {
+                var urlObj = new URL(globalThis.location.href);
+                urlObj.searchParams.forEach(function (value, key) {
+                    // Only add if the property doesn't already exist and is not excluded
+                    if (isUndefined(pageProps[key]) && !PAGE_PROPERTIES_EXCLUDED_FIELDS.has(key)) {
+                        pageProps[key] = value;
+                    }
+                });
+            }
+            catch (error) {
+                logger.error("Error parsing query parameters for page properties:", error);
+            }
             return pageProps;
         };
+        this.options = options;
+        // Compile regex pattern once for better performance
+        if ((_a = options === null || options === void 0 ? void 0 : options.referral) === null || _a === void 0 ? void 0 : _a.pathPattern) {
+            try {
+                this.compiledPathPattern = new RegExp(options.referral.pathPattern);
+            }
+            catch (error) {
+                logger.warn("Invalid referral path pattern: ".concat(options.referral.pathPattern, ". Error: ").concat(error));
+            }
+        }
     }
     EventFactory.prototype.getTimezone = function () {
         try {
@@ -178,22 +227,45 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.getLibraryVersion = function () {
         return version;
     };
+    // Get screen dimensions and pixel density
+    // Returns safe defaults if any error occurs to ensure event creation continues
+    EventFactory.prototype.getScreen = function () {
+        var _a, _b;
+        var safeDefaults = {
+            screen_width: 0,
+            screen_height: 0,
+            screen_density: 1,
+            viewport_width: 0,
+            viewport_height: 0,
+        };
+        try {
+            return {
+                screen_width: ((_a = globalThis.screen) === null || _a === void 0 ? void 0 : _a.width) || 0,
+                screen_height: ((_b = globalThis.screen) === null || _b === void 0 ? void 0 : _b.height) || 0,
+                screen_density: globalThis.devicePixelRatio || 1,
+                viewport_width: globalThis.innerWidth || 0,
+                viewport_height: globalThis.innerHeight || 0,
+            };
+        }
+        catch (error) {
+            logger.error("Error resolving screen properties:", error);
+            return safeDefaults;
+        }
+    };
     // Contextual fields that are automatically collected and populated by the Formo SDK
     EventFactory.prototype.generateContext = function (context) {
         return __awaiter(this, void 0, void 0, function () {
-            var path, browserName, language, timezone, location, library_version, defaultContext, mergedContext;
+            var browserName, language, timezone, location, library_version, defaultContext, mergedContext;
             return __generator(this, function (_a) {
                 switch (_a.label) {
-                    case 0:
-                        path = globalThis.location.pathname;
-                        return [4 /*yield*/, detectBrowser()];
+                    case 0: return [4 /*yield*/, detectBrowser()];
                     case 1:
                         browserName = _a.sent();
                         language = this.getLanguage();
                         timezone = this.getTimezone();
                         location = this.getLocation();
                         library_version = this.getLibraryVersion();
-                        defaultContext = __assign(__assign({ user_agent: globalThis.navigator.userAgent, locale: language, timezone: timezone, location: location }, this.getTrafficSources(globalThis.location.href)), { page_path: path, page_title: document.title, page_url: globalThis.location.href, library_name: "Formo Web SDK", library_version: library_version, browser: browserName });
+                        defaultContext = __assign(__assign(__assign({ user_agent: globalThis.navigator.userAgent, locale: language, timezone: timezone, location: location }, this.getTrafficSources(globalThis.location.href)), { page_title: document.title, page_url: globalThis.location.href, library_name: "Formo Web SDK", library_version: library_version, browser: browserName }), this.getScreen());
                         mergedContext = mergeDeepRight(defaultContext, context || {});
                         return [2 /*return*/, mergedContext];
                 }
@@ -241,7 +313,7 @@ var EventFactory = /** @class */ (function () {
         return __awaiter(this, void 0, void 0, function () {
             var props, pageEvent;
             return __generator(this, function (_a) {
-                props = properties !== null && properties !== void 0 ? properties : {};
+                props = __assign({}, (properties !== null && properties !== void 0 ? properties : {}));
                 props.category = category;
                 props.name = name;
                 props = this.getPageProperties(props);

package/dist/esm/src/lib/event/EventManager.d.ts

@@ -1,4 +1,4 @@
-import { Address, APIEvent } from "../../types";
+import { Address, APIEvent, Options } from "../../types";
 import { IEventQueue } from "../queue";
 import { IEventFactory, IEventManager } from "./type";
 /**
@@ -10,8 +10,9 @@ declare class EventManager implements IEventManager {
     /**
      *
      * @param eventQueue Event queue instance
+     * @param options Optional configuration (referral parsing, etc.)
      */
-    constructor(eventQueue: IEventQueue);
+    constructor(eventQueue: IEventQueue, options?: Options);
     /**
      * Consumes a new incoming event
      * @param event Incoming event data

package/dist/esm/src/lib/event/EventManager.js

@@ -55,10 +55,11 @@ var EventManager = /** @class */ (function () {
     /**
      *
      * @param eventQueue Event queue instance
+     * @param options Optional configuration (referral parsing, etc.)
      */
-    function EventManager(eventQueue) {
+    function EventManager(eventQueue, options) {
         this.eventQueue = eventQueue;
-        this.eventFactory = new EventFactory();
+        this.eventFactory = new EventFactory(options);
     }
     /**
      * Consumes a new incoming event

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

@@ -1,4 +1,11 @@
 declare const CHANNEL = "web";
 declare const VERSION = "0";
-export { CHANNEL, VERSION };
+/**
+ * Fields that should be excluded from page event properties parsing
+ * These are either:
+ * - Already captured in event context (UTM params, referral params)
+ * - 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 };
 //# sourceMappingURL=constants.d.ts.map

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

@@ -1,4 +1,29 @@
 var CHANNEL = "web";
 var VERSION = "0";
-export { CHANNEL, VERSION };
+/**
+ * Fields that should be excluded from page event properties parsing
+ * These are either:
+ * - Already captured in event context (UTM params, referral params)
+ * - Semantic event properties that should not be overridden by URL params
+ */
+var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set([
+    // Context fields (already captured in event context)
+    'utm_source',
+    'utm_medium',
+    'utm_campaign',
+    'utm_term',
+    'utm_content',
+    'ref',
+    'referral',
+    'refcode',
+    'referrer',
+    // Semantic event properties (should not be overridden by URL params)
+    'category',
+    'name',
+    'url',
+    'path',
+    'hash',
+    'query',
+]);
+export { CHANNEL, VERSION, PAGE_PROPERTIES_EXCLUDED_FIELDS };
 //# sourceMappingURL=constants.js.map

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

@@ -94,6 +94,24 @@ export interface AutocaptureOptions {
      */
     chain?: boolean;
 }
+/**
+ * Configuration options for referral parameter parsing
+ */
+export interface ReferralOptions {
+    /**
+     * Custom query parameter names to check for referral codes
+     * @default ["ref", "referral", "refcode"]
+     * @example ["via", "referrer", "source"] - will check ?via=CODE, ?referrer=CODE, ?source=CODE
+     */
+    queryParams?: string[];
+    /**
+     * URL path pattern to extract referral code from
+     * Should be a regex string that matches the path segment containing the referral code
+     * The first capture group will be used as the referral code
+     * @example "/r/([^/]+)" - will extract "01K17FKB" from "https://glider.fi/r/01K17FKB"
+     */
+    pathPattern?: string;
+}
 export interface Options {
     provider?: EIP1193Provider;
     tracking?: boolean | TrackingOptions;
@@ -122,6 +140,12 @@ export interface Options {
         enabled?: boolean;
         levels?: LogLevel[];
     };
+    /**
+     * Configuration for referral parameter parsing from URLs
+     * Allows customizing how referral codes are detected from query parameters and URL paths
+     * @example { queryParams: ["via"], pathPattern: "/r/([^/]+)" }
+     */
+    referral?: ReferralOptions;
     ready?: (formo: IFormoAnalytics) => void;
 }
 export interface FormoAnalyticsProviderProps {

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

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

package/dist/esm/src/version.js

@@ -0,0 +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.25.0';
+//# sourceMappingURL=version.js.map