@formo/analytics 1.31.0 → 1.33.0

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

@@ -46,6 +46,15 @@ var __generator = (this && this.__generator) || function (thisArg, body) {
         if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
     }
 };
+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 __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
@@ -67,7 +76,7 @@ var ISO_3166_ALPHA_2_REGEX = /^[A-Z]{2}$/;
 var EventFactory = /** @class */ (function () {
     function EventFactory(options) {
         var _this = this;
-        var _a;
+        var _a, _b;
         this.extractUTMParameters = function (url) {
             var result = {
                 utm_campaign: "",
@@ -145,12 +154,16 @@ var EventFactory = /** @class */ (function () {
                     return "";
             }
             catch (_b) { }
-            return ref;
+            return _this.redactUrl(ref);
         };
         this.getTrafficSources = function (url) {
             var urlObj = new URL(url);
             var contextTrafficSources = __assign(__assign(__assign({}, _this.extractUTMParameters(url)), _this.extractClickIdParameters(urlObj)), { ref: _this.extractReferralParameter(urlObj), referrer: _this.getExternalReferrer() });
-            var storedTrafficSources = (0, storage_1.session)().get(constants_1.SESSION_TRAFFIC_SOURCE_KEY) || {};
+            // Sticky traffic sources may have been persisted by an older SDK version or
+            // a looser config, before the current excludeQueryParams was in effect.
+            // Honor the current denylist on the way out so excluded values can never
+            // resurface from session storage (or get re-persisted below).
+            var storedTrafficSources = _this.redactStoredTrafficSources((0, storage_1.session)().get(constants_1.SESSION_TRAFFIC_SOURCE_KEY) || {});
             var mergedClickIds = {};
             for (var _i = 0, CLICK_ID_PARAMS_2 = constants_2.CLICK_ID_PARAMS; _i < CLICK_ID_PARAMS_2.length; _i++) {
                 var p = CLICK_ID_PARAMS_2[_i];
@@ -191,8 +204,17 @@ var EventFactory = /** @class */ (function () {
         this.getPageProperties = function (properties) {
             // Create a copy to avoid mutating the original properties object
             var pageProps = __assign({}, properties);
+            // Parse the current URL once and strip any excluded (sensitive) query
+            // params up front, so nothing sensitive is forwarded via url, query, or the
+            // per-param explosion below. The hash/fragment is intentionally untouched.
+            var urlObj = null;
+            try {
+                urlObj = new URL(globalThis.location.href);
+                _this.redactQueryParams(urlObj);
+            }
+            catch (_a) { }
             if ((0, validators_1.isUndefined)(pageProps.url)) {
-                pageProps.url = new URL(globalThis.location.href).href;
+                pageProps.url = urlObj ? urlObj.href : globalThis.location.href;
             }
             if ((0, validators_1.isUndefined)(pageProps.path)) {
                 pageProps.path = globalThis.location.pathname;
@@ -202,18 +224,22 @@ var EventFactory = /** @class */ (function () {
             }
             // Add query string without the '?' prefix
             if ((0, validators_1.isUndefined)(pageProps.query)) {
-                pageProps.query = globalThis.location.search.slice(1);
+                pageProps.query = urlObj
+                    ? urlObj.search.slice(1)
+                    : 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
+            // Skip fields that are already captured in context or are semantic event properties.
+            // Excluded params were already removed from urlObj above.
             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;
-                    }
-                });
+                if (urlObj) {
+                    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);
@@ -221,8 +247,13 @@ var EventFactory = /** @class */ (function () {
             return pageProps;
         };
         this.options = options;
+        var tracking = options === null || options === void 0 ? void 0 : options.tracking;
+        var configuredExcludes = typeof tracking === "object" ? (_a = tracking.excludeQueryParams) !== null && _a !== void 0 ? _a : [] : [];
+        this.excludedQueryParams = new Set(__spreadArray(__spreadArray([], constants_2.DEFAULT_EXCLUDED_QUERY_PARAMS, true), configuredExcludes, true).map(function (key) {
+            return key.toLowerCase();
+        }));
         // 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) {
+        if ((_b = options === null || options === void 0 ? void 0 : options.referral) === null || _b === void 0 ? void 0 : _b.pathPattern) {
             try {
                 this.compiledPathPattern = new RegExp(options.referral.pathPattern);
             }
@@ -245,13 +276,7 @@ var EventFactory = /** @class */ (function () {
         return (0, address_1.validateAddress)(address, chainId) || null;
     };
     EventFactory.prototype.getTimezone = function () {
-        try {
-            return Intl.DateTimeFormat().resolvedOptions().timeZone;
-        }
-        catch (error) {
-            logger_1.logger.error("Error resolving timezone:", error);
-            return "";
-        }
+        return (0, utils_1.getTimezone)();
     };
     EventFactory.prototype.getLocation = function () {
         try {
@@ -284,6 +309,66 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.getLibraryVersion = function () {
         return version_1.version;
     };
+    EventFactory.prototype.isExcludedQueryParam = function (key) {
+        return this.excludedQueryParams.has(key.toLowerCase());
+    };
+    /**
+     * 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.
+     */
+    EventFactory.prototype.redactQueryParams = function (url) {
+        var _this = this;
+        // Collect first, then delete: mutating searchParams while iterating is
+        // unsafe, and deleting a key removes all of its values at once.
+        var keysToDelete = new Set();
+        url.searchParams.forEach(function (_value, key) {
+            if (_this.isExcludedQueryParam(key)) {
+                keysToDelete.add(key);
+            }
+        });
+        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).
+     */
+    EventFactory.prototype.redactUrl = function (href) {
+        if (!href)
+            return href;
+        try {
+            var url = new URL(href);
+            this.redactQueryParams(url);
+            return url.href;
+        }
+        catch (_a) {
+            return href;
+        }
+    };
+    /**
+     * Apply the current query-param denylist to a previously-persisted traffic
+     * source object. Traffic-source keys (utm_*, click ids, ref) are themselves
+     * query-parameter names, so an excluded key's stored value is dropped; the
+     * referrer is a URL and is re-redacted. Guards against a stored value
+     * outliving the config (or SDK version) under which it was first captured.
+     */
+    EventFactory.prototype.redactStoredTrafficSources = function (stored) {
+        var result = {};
+        for (var _i = 0, _a = Object.keys(stored); _i < _a.length; _i++) {
+            var key = _a[_i];
+            var value = stored[key];
+            if (key === "referrer") {
+                result[key] = this.redactUrl(value || "");
+            }
+            else if (this.isExcludedQueryParam(key)) {
+                result[key] = "";
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    };
     // Get screen dimensions and pixel density
     // Returns safe defaults if any error occurs to ensure event creation continues
     EventFactory.prototype.getScreen = function () {
@@ -312,7 +397,7 @@ var EventFactory = /** @class */ (function () {
     // 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 browserName, language, timezone, location, library_version, defaultContext, mergedContext;
+            var browserName, language, timezone, location, library_version, redactedHref, defaultContext, mergedContext;
             return __generator(this, function (_a) {
                 switch (_a.label) {
                     case 0: return [4 /*yield*/, (0, browsers_1.detectBrowser)()];
@@ -322,7 +407,8 @@ var EventFactory = /** @class */ (function () {
                         timezone = this.getTimezone();
                         location = this.getLocation();
                         library_version = this.getLibraryVersion();
-                        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());
+                        redactedHref = this.redactUrl(globalThis.location.href);
+                        defaultContext = __assign(__assign(__assign({ user_agent: globalThis.navigator.userAgent, locale: language, timezone: timezone, location: location }, this.getTrafficSources(redactedHref)), { page_title: document.title, page_url: redactedHref, library_name: "Formo Web SDK", library_version: library_version, browser: browserName }), this.getScreen());
                         mergedContext = (0, mergeDeepRight_1.default)(defaultContext, context || {});
                         return [2 /*return*/, mergedContext];
                 }

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

@@ -6,6 +6,18 @@ declare const VERSION = "0";
  * 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"];
+/**
+ * Query parameters that are ALWAYS stripped from forwarded and stored URLs,
+ * regardless of consumer configuration, because they carry high-sensitivity
+ * secrets that must never reach Formo:
+ * - privy_oauth_code:     Privy OAuth authorization code
+ * - privy_oauth_state:    Privy OAuth CSRF state token
+ * - privy_oauth_provider: Privy OAuth provider identifier
+ *
+ * Consumers can extend the denylist via `tracking.excludeQueryParams` but
+ * cannot remove these built-ins. Matched case-insensitively.
+ */
+declare const DEFAULT_EXCLUDED_QUERY_PARAMS: readonly ["privy_oauth_code", "privy_oauth_state", "privy_oauth_provider"];
 /**
  * Fields that should be excluded from page event properties parsing
  * These are either:
@@ -13,5 +25,5 @@ declare const CLICK_ID_PARAMS: readonly ["gclid", "gad_source", "fbclid", "msclk
  * - 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, PAGE_PROPERTIES_EXCLUDED_FIELDS };
+export { CHANNEL, VERSION, CLICK_ID_PARAMS, DEFAULT_EXCLUDED_QUERY_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS, };
 //# sourceMappingURL=constants.d.ts.map

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

@@ -9,7 +9,7 @@ var __spreadArray = (this && this.__spreadArray) || function (to, from, pack) {
     return to.concat(ar || Array.prototype.slice.call(from));
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PAGE_PROPERTIES_EXCLUDED_FIELDS = exports.CLICK_ID_PARAMS = exports.VERSION = exports.CHANNEL = void 0;
+exports.PAGE_PROPERTIES_EXCLUDED_FIELDS = exports.DEFAULT_EXCLUDED_QUERY_PARAMS = exports.CLICK_ID_PARAMS = exports.VERSION = exports.CHANNEL = void 0;
 var CHANNEL = "web";
 exports.CHANNEL = CHANNEL;
 var VERSION = "0";
@@ -30,6 +30,23 @@ var CLICK_ID_PARAMS = [
     "ttclid", // TikTok Ads
 ];
 exports.CLICK_ID_PARAMS = CLICK_ID_PARAMS;
+/**
+ * Query parameters that are ALWAYS stripped from forwarded and stored URLs,
+ * regardless of consumer configuration, because they carry high-sensitivity
+ * secrets that must never reach Formo:
+ * - privy_oauth_code:     Privy OAuth authorization code
+ * - privy_oauth_state:    Privy OAuth CSRF state token
+ * - privy_oauth_provider: Privy OAuth provider identifier
+ *
+ * Consumers can extend the denylist via `tracking.excludeQueryParams` but
+ * cannot remove these built-ins. Matched case-insensitively.
+ */
+var DEFAULT_EXCLUDED_QUERY_PARAMS = [
+    "privy_oauth_code",
+    "privy_oauth_state",
+    "privy_oauth_provider",
+];
+exports.DEFAULT_EXCLUDED_QUERY_PARAMS = DEFAULT_EXCLUDED_QUERY_PARAMS;
 /**
  * Fields that should be excluded from page event properties parsing
  * These are either:

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

@@ -72,6 +72,34 @@ export interface TrackingOptions {
     excludeHosts?: string[];
     excludePaths?: string[];
     excludeChains?: ChainID[];
+    /**
+     * IANA timezone names to opt out of tracking entirely. When the visitor's
+     * resolved timezone (via `Intl.DateTimeFormat().resolvedOptions().timeZone`)
+     * matches one of these, no events are enqueued or sent — including `identify`
+     * and `connect`. Matched case-insensitively against the full timezone string.
+     *
+     * Note: this is client-side, timezone-derived geolocation. It is best-effort
+     * and can be bypassed (a VPN does not change the browser timezone, and users
+     * can change their OS timezone). For authoritative jurisdiction blocking, use
+     * server-side IP geolocation at your ingest endpoint instead.
+     *
+     * @example ["Europe/London", "America/New_York"]
+     */
+    excludeTimezones?: string[];
+    /**
+     * Additional query parameter names to strip from forwarded and stored URLs,
+     * on top of a built-in always-on denylist (currently `privy_oauth_code`,
+     * `privy_oauth_state`, and `privy_oauth_provider`) that cannot be disabled.
+     * Matched case-insensitively. Excluded params are stripped from the captured
+     * page URL, query string, per-parameter page properties, and referrer before
+     * any event is sent. The URL hash/fragment is intentionally left untouched.
+     *
+     * Mirrors Mixpanel's `property_blacklist` and PostHog's `property_denylist`,
+     * scoped here to URL query parameters.
+     *
+     * @example ["token", "access_token", "email", "signature"]
+     */
+    excludeQueryParams?: string[];
 }
 /**
  * Configuration options for controlling wallet event autocapture

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

@@ -3,4 +3,5 @@ export * from "./base";
 export * from "./converter";
 export * from "./generate";
 export * from "./hash";
+export * from "./timezone";
 //# sourceMappingURL=index.d.ts.map

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.
      */