@formo/analytics 1.32.0 → 1.33.1

package/dist/cjs/src/utils/index.js

@@ -19,4 +19,5 @@ __exportStar(require("./base"), exports);
 __exportStar(require("./converter"), exports);
 __exportStar(require("./generate"), exports);
 __exportStar(require("./hash"), exports);
+__exportStar(require("./timezone"), exports);
 //# sourceMappingURL=index.js.map

package/dist/cjs/src/utils/timezone.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve the current IANA timezone (e.g. "Europe/London") via the Intl API.
+ * Returns "" when the timezone cannot be resolved (e.g. Intl unavailable).
+ */
+declare const getTimezone: () => string;
+export { getTimezone };
+//# sourceMappingURL=timezone.d.ts.map

package/dist/cjs/src/utils/timezone.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getTimezone = void 0;
+var logger_1 = require("../logger");
+/**
+ * Resolve the current IANA timezone (e.g. "Europe/London") via the Intl API.
+ * Returns "" when the timezone cannot be resolved (e.g. Intl unavailable).
+ */
+var getTimezone = function () {
+    try {
+        return Intl.DateTimeFormat().resolvedOptions().timeZone || "";
+    }
+    catch (error) {
+        logger_1.logger.error("Error resolving timezone:", error);
+        return "";
+    }
+};
+exports.getTimezone = getTimezone;
+//# sourceMappingURL=timezone.js.map

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

@@ -282,6 +282,59 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private static installHistoryHooksOnce;
     private trackPageHit;
     private trackEvent;
+    /**
+     * Visitor-level tracking suppression.
+     *
+     * Returns true when the SDK must not persist any identity/session/chain
+     * state or send any events for this visitor — i.e. an explicit opt-out or a
+     * jurisdiction/timezone exclusion. Public entry points that write state
+     * before reaching the `shouldTrack()` event gate (identify/connect/detect)
+     * check this first so suppressed visitors leave no cookies or session state.
+     * @returns {boolean} True if all tracking and persistence must be suppressed
+     */
+    private isTrackingSuppressed;
+    /**
+     * Whether the current environment is excluded from tracking — the visitor's
+     * timezone, the current hostname, or the current pathname matches a
+     * configured exclusion.
+     *
+     * Timezone is visitor/session-level (stable for the session); host/path are
+     * current-page-level and transient — if a SPA navigates to an allowed path,
+     * tracking resumes for future actions. Used as the "do not write identity or
+     * send events" gate at every entry point that would persist state before the
+     * `shouldTrack()` event gate.
+     * @returns {boolean} True if the current environment is excluded
+     */
+    private isCurrentEnvironmentExcluded;
+    /**
+     * Whether the current hostname matches a configured `tracking.excludeHosts`
+     * entry (exact match). Current-page-level — see isCurrentEnvironmentExcluded.
+     * @returns {boolean} True if the current hostname is excluded
+     */
+    private isHostExcluded;
+    /**
+     * Whether the current pathname matches a configured `tracking.excludePaths`
+     * entry (exact match). Current-page-level — see isCurrentEnvironmentExcluded.
+     * @returns {boolean} True if the current pathname is excluded
+     */
+    private isPathExcluded;
+    /**
+     * Whether the current call is in a visitor-level suppression state — opt-out
+     * or excluded timezone — for which any persisted identity cookie should be
+     * actively purged (not merely skipped). Host/path exclusions are
+     * deliberately excluded here: they are transient current-page states, so a
+     * cookie legitimately written on an allowed page must survive a visit to an
+     * excluded route.
+     * @returns {boolean} True if persisted identity must be purged
+     */
+    private isPersistedIdentityPurgeRequired;
+    /**
+     * Whether the visitor's browser-resolved timezone matches a configured
+     * `tracking.excludeTimezones` entry (case-insensitive). Client-side and
+     * best-effort — see TrackingOptions.excludeTimezones.
+     * @returns {boolean} True if the current timezone is excluded
+     */
+    private isTimezoneExcluded;
     /**
      * Determines if tracking should be enabled based on configuration and consent
      * @returns {boolean} True if tracking should be enabled
@@ -329,6 +382,14 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * value in the normal way; existing connections are never clobbered.
      */
     private backfillActiveWallet;
+    /**
+     * Apply an EVM autocapture connect/switch while tracking is suppressed
+     * (opt-out / timezone / excluded host or path): never LEARN the wallet, but
+     * if it is a switch away from an already-learned EVM wallet, drop the stale
+     * one (which also clears the active-wallet cookie) so it can't attach to a
+     * later allowed-page event.
+     */
+    private clearStaleEvmWalletOnSwitchWhileSuppressed;
     /**
      * Polls for transaction receipt and emits tx.status = CONFIRMED or REVERTED.
      */

package/dist/esm/src/FormoAnalytics.js

@@ -66,6 +66,7 @@ import { detectInjectedProviderInfo, isValidProvider } from "./provider";
 import { FormoAnalyticsSession, SESSION_WALLET_DETECTED_KEY, SESSION_WALLET_IDENTIFIED_KEY, } from "./session";
 import { SignatureStatus, TransactionStatus, WRAPPED_REQUEST_SYMBOL, WRAPPED_REQUEST_REF_SYMBOL, } from "./types";
 import { validateAddress, validateAndChecksumAddress } from "./utils/address";
+import { getTimezone } from "./utils/timezone";
 import { isLocalhost } from "./validators";
 import { parseChainId } from "./utils/chain";
 import { WagmiEventHandler } from "./wagmi";
@@ -391,6 +392,14 @@ var FormoAnalytics = /** @class */ (function () {
                             logger.warn("Connect: Invalid address provided (\"".concat(address, "\"). Please provide a valid EVM or Solana address."));
                             return [2 /*return*/];
                         }
+                        // connect() persists wallet/chain state (active-wallet cookie,
+                        // currentAddress/currentChainId) before trackEvent's consent check —
+                        // gate the whole method so a suppressed visitor or excluded environment
+                        // (opt-out / timezone / host / path) leaves no session state.
+                        if (this.isTrackingSuppressed()) {
+                            logger.info("connect() skipped: tracking is suppressed for this visitor or environment");
+                            return [2 /*return*/];
+                        }
                         this.setChainState(chainId, { address: validAddress });
                         return [4 /*yield*/, this.trackEvent(EventType.CONNECT, {
                                 chainId: chainId,
@@ -578,10 +587,11 @@ var FormoAnalytics = /** @class */ (function () {
                     case 0:
                         _d.trys.push([0, 12, , 13]);
                         // identify() writes the user-id cookie and marks wallet
-                        // identification before trackEvent's consent check — gate the
-                        // whole method so an opted-out user gets no identity persistence.
-                        if (this.hasOptedOutTracking()) {
-                            logger.info("identify() skipped: user has opted out of tracking");
+                        // identification before trackEvent's consent check — gate the whole
+                        // method so a suppressed visitor or excluded environment (opt-out /
+                        // timezone / host / path) gets no identity persistence.
+                        if (this.isTrackingSuppressed()) {
+                            logger.info("identify() skipped: tracking is suppressed for this visitor or environment");
                             return [2 /*return*/];
                         }
                         if (!!params) return [3 /*break*/, 10];
@@ -709,9 +719,10 @@ var FormoAnalytics = /** @class */ (function () {
                 switch (_c.label) {
                     case 0:
                         // detect() marks wallet detection (a cookie write) before
-                        // trackEvent's consent check — gate it on opt-out.
-                        if (this.hasOptedOutTracking()) {
-                            logger.info("detect() skipped: user has opted out of tracking");
+                        // trackEvent's consent check — gate it for a suppressed visitor or
+                        // excluded environment (opt-out / timezone / host / path).
+                        if (this.isTrackingSuppressed()) {
+                            logger.info("detect() skipped: tracking is suppressed for this visitor or environment");
                             return [2 /*return*/];
                         }
                         if (this.session.isWalletDetected(rdns))
@@ -1075,9 +1086,16 @@ var FormoAnalytics = /** @class */ (function () {
                     case 26:
                         nextChainId = _a.sent();
                         wasDisconnected = !this._evmAddress;
-                        // CRITICAL: Always update state regardless of whether connect tracking is enabled
-                        // This ensures disconnect events will have valid address/chainId values
-                        this.setChainState('evm', { address: address, chainId: nextChainId });
+                        // Update state regardless of whether connect *event* tracking is enabled,
+                        // so disconnect events keep valid address/chainId values. (excludeChains is
+                        // NOT suppression — it still updates state so currentChainId can gate
+                        // events.)
+                        if (this.isTrackingSuppressed()) {
+                            this.clearStaleEvmWalletOnSwitchWhileSuppressed(address);
+                        }
+                        else {
+                            this.setChainState('evm', { address: address, chainId: nextChainId });
+                        }
                         providerInfo = this.getProviderInfo(provider);
                         effectiveChainId = nextChainId || 0;
                         if (this.isAutocaptureEnabled("connect")) {
@@ -1250,13 +1268,19 @@ var FormoAnalytics = /** @class */ (function () {
                                 this._provider = provider;
                             }
                             isActiveProvider = this._provider === provider;
-                            // CRITICAL: Always update state from active provider regardless of tracking config
-                            // This ensures disconnect events will have valid address/chainId values
+                            // Update state from active provider so disconnect events keep valid
+                            // address/chainId values — except while suppressed, where we must not
+                            // LEARN identity (only drop a stale EVM wallet on a switch).
                             if (isActiveProvider) {
-                                this.setChainState('evm', {
-                                    chainId: chainId,
-                                    address: validateAndChecksumAddress(address) || undefined,
-                                });
+                                if (this.isTrackingSuppressed()) {
+                                    this.clearStaleEvmWalletOnSwitchWhileSuppressed(address);
+                                }
+                                else {
+                                    this.setChainState('evm', {
+                                        chainId: chainId,
+                                        address: validateAndChecksumAddress(address) || undefined,
+                                    });
+                                }
                             }
                             // Conditionally emit connect event based on tracking configuration
                             if (isActiveProvider && this._evmAddress) {
@@ -1625,6 +1649,108 @@ var FormoAnalytics = /** @class */ (function () {
             });
         });
     };
+    /**
+     * Visitor-level tracking suppression.
+     *
+     * Returns true when the SDK must not persist any identity/session/chain
+     * state or send any events for this visitor — i.e. an explicit opt-out or a
+     * jurisdiction/timezone exclusion. Public entry points that write state
+     * before reaching the `shouldTrack()` event gate (identify/connect/detect)
+     * check this first so suppressed visitors leave no cookies or session state.
+     * @returns {boolean} True if all tracking and persistence must be suppressed
+     */
+    FormoAnalytics.prototype.isTrackingSuppressed = function () {
+        return this.hasOptedOutTracking() || this.isCurrentEnvironmentExcluded();
+    };
+    /**
+     * Whether the current environment is excluded from tracking — the visitor's
+     * timezone, the current hostname, or the current pathname matches a
+     * configured exclusion.
+     *
+     * Timezone is visitor/session-level (stable for the session); host/path are
+     * current-page-level and transient — if a SPA navigates to an allowed path,
+     * tracking resumes for future actions. Used as the "do not write identity or
+     * send events" gate at every entry point that would persist state before the
+     * `shouldTrack()` event gate.
+     * @returns {boolean} True if the current environment is excluded
+     */
+    FormoAnalytics.prototype.isCurrentEnvironmentExcluded = function () {
+        return (this.isTimezoneExcluded() ||
+            this.isHostExcluded() ||
+            this.isPathExcluded());
+    };
+    /**
+     * Whether the current hostname matches a configured `tracking.excludeHosts`
+     * entry (exact match). Current-page-level — see isCurrentEnvironmentExcluded.
+     * @returns {boolean} True if the current hostname is excluded
+     */
+    FormoAnalytics.prototype.isHostExcluded = function () {
+        var tracking = this.options.tracking;
+        if (tracking === null ||
+            typeof tracking !== "object" ||
+            Array.isArray(tracking)) {
+            return false;
+        }
+        if (typeof window === "undefined") {
+            return false;
+        }
+        var _a = tracking.excludeHosts, excludeHosts = _a === void 0 ? [] : _a;
+        return excludeHosts.includes(window.location.hostname);
+    };
+    /**
+     * Whether the current pathname matches a configured `tracking.excludePaths`
+     * entry (exact match). Current-page-level — see isCurrentEnvironmentExcluded.
+     * @returns {boolean} True if the current pathname is excluded
+     */
+    FormoAnalytics.prototype.isPathExcluded = function () {
+        var tracking = this.options.tracking;
+        if (tracking === null ||
+            typeof tracking !== "object" ||
+            Array.isArray(tracking)) {
+            return false;
+        }
+        if (typeof window === "undefined") {
+            return false;
+        }
+        var _a = tracking.excludePaths, excludePaths = _a === void 0 ? [] : _a;
+        return excludePaths.includes(window.location.pathname);
+    };
+    /**
+     * Whether the current call is in a visitor-level suppression state — opt-out
+     * or excluded timezone — for which any persisted identity cookie should be
+     * actively purged (not merely skipped). Host/path exclusions are
+     * deliberately excluded here: they are transient current-page states, so a
+     * cookie legitimately written on an allowed page must survive a visit to an
+     * excluded route.
+     * @returns {boolean} True if persisted identity must be purged
+     */
+    FormoAnalytics.prototype.isPersistedIdentityPurgeRequired = function () {
+        return this.hasOptedOutTracking() || this.isTimezoneExcluded();
+    };
+    /**
+     * Whether the visitor's browser-resolved timezone matches a configured
+     * `tracking.excludeTimezones` entry (case-insensitive). Client-side and
+     * best-effort — see TrackingOptions.excludeTimezones.
+     * @returns {boolean} True if the current timezone is excluded
+     */
+    FormoAnalytics.prototype.isTimezoneExcluded = function () {
+        var tracking = this.options.tracking;
+        if (tracking === null ||
+            typeof tracking !== "object" ||
+            Array.isArray(tracking)) {
+            return false;
+        }
+        var _a = tracking.excludeTimezones, excludeTimezones = _a === void 0 ? [] : _a;
+        if (excludeTimezones.length === 0) {
+            return false;
+        }
+        var timezone = getTimezone();
+        if (!timezone) {
+            return false;
+        }
+        var lowerTimezone = timezone.toLowerCase();
+        return excludeTimezones.some(function (tz) { return typeof tz === "string" && tz.toLowerCase() === lowerTimezone; });
+    };
     /**
      * Determines if tracking should be enabled based on configuration and consent
      * @returns {boolean} True if tracking should be enabled
@@ -1642,20 +1768,11 @@ var FormoAnalytics = /** @class */ (function () {
         if (this.options.tracking !== null &&
             typeof this.options.tracking === "object" &&
             !Array.isArray(this.options.tracking)) {
-            var _a = this.options.tracking, _b = _a.excludeHosts, excludeHosts = _b === void 0 ? [] : _b, _c = _a.excludePaths, excludePaths = _c === void 0 ? [] : _c, _d = _a.excludeChains, excludeChains = _d === void 0 ? [] : _d;
-            // Check hostname exclusions - use exact matching
-            if (excludeHosts.length > 0 && typeof window !== "undefined") {
-                var hostname = window.location.hostname;
-                if (excludeHosts.includes(hostname)) {
-                    return false;
-                }
-            }
-            // Check path exclusions - use exact matching
-            if (excludePaths.length > 0 && typeof window !== "undefined") {
-                var pathname = window.location.pathname;
-                if (excludePaths.includes(pathname)) {
-                    return false;
-                }
+            var _a = this.options.tracking.excludeChains, excludeChains = _a === void 0 ? [] : _a;
+            // Environment exclusions (timezone / host / path) — no identify / connect
+            // / track events while excluded. Host/path are exact-match.
+            if (this.isCurrentEnvironmentExcluded()) {
+                return false;
             }
             // Check chainId exclusions
             if (excludeChains.length > 0 &&
@@ -2046,10 +2163,31 @@ var FormoAnalytics = /** @class */ (function () {
      * value in the normal way; existing connections are never clobbered.
      */
     FormoAnalytics.prototype.backfillActiveWallet = function (address, chainId) {
+        // Never learn identity while suppressed (opt-out / timezone / excluded host
+        // or path). A signature/transaction observed on an excluded route must not
+        // populate currentAddress for later allowed-page events. backfill only ever
+        // *adds* an address (it no-ops when one is already known), so there is no
+        // stale state to clear here.
+        if (this.isTrackingSuppressed())
+            return;
         if (this._evmAddress)
             return;
         this.setChainState('evm', { address: address, chainId: chainId });
     };
+    /**
+     * Apply an EVM autocapture connect/switch while tracking is suppressed
+     * (opt-out / timezone / excluded host or path): never LEARN the wallet, but
+     * if it is a switch away from an already-learned EVM wallet, drop the stale
+     * one (which also clears the active-wallet cookie) so it can't attach to a
+     * later allowed-page event.
+     */
+    FormoAnalytics.prototype.clearStaleEvmWalletOnSwitchWhileSuppressed = function (address) {
+        var evmAddress = this._chainState.evm.address;
+        var incoming = validateAndChecksumAddress(address);
+        if (evmAddress && incoming && incoming !== evmAddress) {
+            this.clearChainState('evm');
+        }
+    };
     /**
      * Polls for transaction receipt and emits tx.status = CONFIRMED or REVERTED.
      */
@@ -2256,6 +2394,39 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.syncWalletState = function (params) {
         var chainId = params.chainId, address = params.address;
+        if (this.isTrackingSuppressed()) {
+            // While suppressed (opt-out / timezone / excluded host or path) we must
+            // never LEARN a new wallet — but we must still CLEAR stale identity.
+            // Otherwise a disconnect or wallet switch observed on a suppressed route
+            // would leave the previously-learned address in memory and in the
+            // active-wallet cookie, attaching it to later allowed-page events.
+            if (!address) {
+                // Disconnect: drop the affected namespace(s).
+                if (chainId !== undefined && chainId !== null) {
+                    this.clearChainState(chainId);
+                }
+                else {
+                    this.clearChainState("evm");
+                    this.clearChainState("solana");
+                }
+                return;
+            }
+            // Address present: a switch away from the wallet already learned in this
+            // namespace invalidates it. Drop the stale one without learning the new
+            // address; a fresh connect (nothing learned yet) or a re-confirmation of
+            // the same address is a no-op.
+            if (chainId === null || chainId === undefined)
+                return;
+            var namespace = this.getNamespace(chainId);
+            var namespaceAddress = this._chainState[namespace].address;
+            var validIncoming = validateAddress(address, chainId);
+            if (namespaceAddress &&
+                validIncoming &&
+                validIncoming !== namespaceAddress) {
+                this.clearChainState(chainId);
+            }
+            return;
+        }
         if (!address) {
             if (chainId !== undefined && chainId !== null) {
                 this.clearChainState(chainId);
@@ -2313,18 +2484,28 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.persistActiveWallet = function () {
         try {
-            // Never write an identity cookie for an opted-out user; ensure any
-            // prior snapshot is removed instead.
-            if (this.hasOptedOutTracking()) {
+            // Visitor-level suppression (opt-out or excluded timezone): purge any
+            // prior snapshot — these are stable for the session, so deletion is safe.
+            if (this.isPersistedIdentityPurgeRequired()) {
                 cookie().remove(ACTIVE_WALLET_KEY);
                 return;
             }
             if (this.currentAddress) {
+                // Current-page exclusion (host/path): do not write a new snapshot while
+                // on an excluded route, but leave any existing cookie intact. A cookie
+                // written on an allowed page must survive a transient visit to an
+                // excluded one (passive navigation does not call this method).
+                if (this.isHostExcluded() || this.isPathExcluded()) {
+                    return;
+                }
                 var value = JSON.stringify(__assign({ address: this.currentAddress }, (this.currentChainId !== undefined && { chainId: this.currentChainId })));
                 var domain = getIdentityCookieDomain(this.crossSubdomainCookies);
                 cookie().set(ACTIVE_WALLET_KEY, value, __assign(__assign({ path: "/", expires: new Date(Date.now() + ACTIVE_WALLET_TTL_MS).toUTCString() }, getIdentityCookieSecurity()), (domain ? { domain: domain } : {})));
             }
             else {
+                // No active wallet → clear the snapshot. This runs even on an excluded
+                // route, so a disconnect/switch observed while suppressed actively
+                // removes stale identity instead of leaving it for later allowed events.
                 cookie().remove(ACTIVE_WALLET_KEY);
             }
         }
@@ -2338,12 +2519,18 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.loadActiveWallet = function () {
         try {
-            // Never restore wallet identity into memory for an opted-out user
-            // (mirrors persistActiveWallet's guard); drop any stale snapshot.
-            if (this.hasOptedOutTracking()) {
+            // Visitor-level suppression (opt-out or excluded timezone): never restore
+            // identity into memory; drop the stale snapshot.
+            if (this.isPersistedIdentityPurgeRequired()) {
                 cookie().remove(ACTIVE_WALLET_KEY);
                 return;
             }
+            // Current-page exclusion (host/path): don't restore into memory while on
+            // an excluded route, but keep the cookie so a later allowed-page load can
+            // restore it.
+            if (this.isHostExcluded() || this.isPathExcluded()) {
+                return;
+            }
             var raw = cookie().get(ACTIVE_WALLET_KEY);
             if (!raw)
                 return;

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

@@ -18,15 +18,21 @@ declare class EventFactory implements IEventFactory {
     private getLanguage;
     private getLibraryVersion;
     private isExcludedQueryParam;
+    /**
+     * Normalize URL paths for analytics aggregation by stripping trailing slashes
+     * from non-root paths. Query strings and hash fragments are preserved by
+     * mutating only the URL pathname.
+     */
+    private normalizeUrlPath;
     /**
      * Strip excluded (sensitive) query parameters from a URL in place. Only the
      * query string is touched; the path and hash/fragment are left as-is.
      */
     private redactQueryParams;
     /**
-     * Return the given absolute URL with excluded query parameters removed. The
-     * input is returned unchanged when it is empty or cannot be parsed (e.g. an
-     * empty referrer).
+     * Return the given absolute URL with excluded query parameters removed and
+     * trailing slashes stripped from non-root paths. The input is returned
+     * unchanged when it is empty or cannot be parsed (e.g. an empty referrer).
      */
     private redactUrl;
     private extractUTMParameters;

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

@@ -55,7 +55,7 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 };
 import { COUNTRY_LIST, LOCAL_ANONYMOUS_ID_KEY, SESSION_TRAFFIC_SOURCE_KEY, } from "../constants";
-import { toSnakeCase } from "../utils";
+import { toSnakeCase, getTimezone } from "../utils";
 import { validateAddress } from "../utils/address";
 import { getCurrentTimeFormatted } from "../utils/timestamp";
 import { isUndefined } from "../validators";
@@ -63,7 +63,7 @@ import { logger } from "../logger";
 import mergeDeepRight from "../ramda/mergeDeepRight";
 import { session } from "../storage";
 import { version } from "../version";
-import { CHANNEL, CLICK_ID_PARAMS, DEFAULT_EXCLUDED_QUERY_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS, VERSION, } from "./constants";
+import { CHANNEL, CLICK_ID_PARAMS, DEFAULT_EXCLUDED_QUERY_PARAMS, DEFAULT_REFERRAL_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}$/;
@@ -107,10 +107,9 @@ var EventFactory = /** @class */ (function () {
             // - 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
+                ? DEFAULT_REFERRAL_PARAMS // No referral config at all → use defaults
+                : ((_b = _this.options.referral.queryParams) !== null && _b !== void 0 ? _b : DEFAULT_REFERRAL_PARAMS); // 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];
@@ -205,13 +204,14 @@ var EventFactory = /** @class */ (function () {
             try {
                 urlObj = new URL(globalThis.location.href);
                 _this.redactQueryParams(urlObj);
+                _this.normalizeUrlPath(urlObj);
             }
             catch (_a) { }
             if (isUndefined(pageProps.url)) {
                 pageProps.url = urlObj ? urlObj.href : globalThis.location.href;
             }
             if (isUndefined(pageProps.path)) {
-                pageProps.path = globalThis.location.pathname;
+                pageProps.path = urlObj ? urlObj.pathname : globalThis.location.pathname;
             }
             if (isUndefined(pageProps.hash)) {
                 pageProps.hash = globalThis.location.hash;
@@ -270,13 +270,7 @@ var EventFactory = /** @class */ (function () {
         return validateAddress(address, chainId) || null;
     };
     EventFactory.prototype.getTimezone = function () {
-        try {
-            return Intl.DateTimeFormat().resolvedOptions().timeZone;
-        }
-        catch (error) {
-            logger.error("Error resolving timezone:", error);
-            return "";
-        }
+        return getTimezone();
     };
     EventFactory.prototype.getLocation = function () {
         try {
@@ -312,6 +306,16 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.isExcludedQueryParam = function (key) {
         return this.excludedQueryParams.has(key.toLowerCase());
     };
+    /**
+     * Normalize URL paths for analytics aggregation by stripping trailing slashes
+     * from non-root paths. Query strings and hash fragments are preserved by
+     * mutating only the URL pathname.
+     */
+    EventFactory.prototype.normalizeUrlPath = function (url) {
+        if (url.pathname !== "/") {
+            url.pathname = url.pathname.replace(/\/+$/, "");
+        }
+    };
     /**
      * Strip excluded (sensitive) query parameters from a URL in place. Only the
      * query string is touched; the path and hash/fragment are left as-is.
@@ -329,9 +333,9 @@ var EventFactory = /** @class */ (function () {
         keysToDelete.forEach(function (key) { return url.searchParams.delete(key); });
     };
     /**
-     * Return the given absolute URL with excluded query parameters removed. The
-     * input is returned unchanged when it is empty or cannot be parsed (e.g. an
-     * empty referrer).
+     * Return the given absolute URL with excluded query parameters removed and
+     * trailing slashes stripped from non-root paths. The input is returned
+     * unchanged when it is empty or cannot be parsed (e.g. an empty referrer).
      */
     EventFactory.prototype.redactUrl = function (href) {
         if (!href)
@@ -339,6 +343,7 @@ var EventFactory = /** @class */ (function () {
         try {
             var url = new URL(href);
             this.redactQueryParams(url);
+            this.normalizeUrlPath(url);
             return url.href;
         }
         catch (_a) {

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

@@ -18,6 +18,15 @@ declare const CLICK_ID_PARAMS: readonly ["gclid", "gad_source", "fbclid", "msclk
  * cannot remove these built-ins. Matched case-insensitively.
  */
 declare const DEFAULT_EXCLUDED_QUERY_PARAMS: readonly ["privy_oauth_code", "privy_oauth_state", "privy_oauth_provider"];
+/**
+ * Default query parameter names checked (in order) for a referral code on the
+ * landing-page URL. The first parameter present supplies the `ref` traffic
+ * source. Consumers can override this list via `referral.queryParams`.
+ *
+ * Keep in sync with the ReferralOptions.queryParams @default in
+ * src/types/base.ts.
+ */
+declare const DEFAULT_REFERRAL_PARAMS: readonly ["ref", "referral", "refcode", "af", "referrer"];
 /**
  * Fields that should be excluded from page event properties parsing
  * These are either:
@@ -25,5 +34,5 @@ declare const DEFAULT_EXCLUDED_QUERY_PARAMS: readonly ["privy_oauth_code", "priv
  * - Semantic event properties that should not be overridden by URL params
  */
 declare const PAGE_PROPERTIES_EXCLUDED_FIELDS: Set<string>;
-export { CHANNEL, VERSION, CLICK_ID_PARAMS, DEFAULT_EXCLUDED_QUERY_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS, };
+export { CHANNEL, VERSION, CLICK_ID_PARAMS, DEFAULT_EXCLUDED_QUERY_PARAMS, DEFAULT_REFERRAL_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS, };
 //# sourceMappingURL=constants.d.ts.map