@formo/analytics 1.31.0 → 1.32.0

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

@@ -3,6 +3,7 @@ import { IEventFactory } from "./type";
 declare class EventFactory implements IEventFactory {
     private options?;
     private compiledPathPattern?;
+    private excludedQueryParams;
     constructor(options?: Options);
     /**
      * Validate an address for both EVM and Solana chains.
@@ -16,6 +17,18 @@ declare class EventFactory implements IEventFactory {
     private getLocation;
     private getLanguage;
     private getLibraryVersion;
+    private isExcludedQueryParam;
+    /**
+     * 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).
+     */
+    private redactUrl;
     private extractUTMParameters;
     private extractClickIdParameters;
     private extractReferralParameter;
@@ -27,6 +40,14 @@ declare class EventFactory implements IEventFactory {
      * first-touch referrer after a direct landing.
      */
     private getExternalReferrer;
+    /**
+     * 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.
+     */
+    private redactStoredTrafficSources;
     private getTrafficSources;
     private getScreen;
     private generateContext;

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);
             }
@@ -284,6 +315,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 +403,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 +413,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,20 @@ export interface TrackingOptions {
     excludeHosts?: string[];
     excludePaths?: string[];
     excludeChains?: ChainID[];
+    /**
+     * 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/esm/src/event/EventFactory.d.ts

@@ -3,6 +3,7 @@ import { IEventFactory } from "./type";
 declare class EventFactory implements IEventFactory {
     private options?;
     private compiledPathPattern?;
+    private excludedQueryParams;
     constructor(options?: Options);
     /**
      * Validate an address for both EVM and Solana chains.
@@ -16,6 +17,18 @@ declare class EventFactory implements IEventFactory {
     private getLocation;
     private getLanguage;
     private getLibraryVersion;
+    private isExcludedQueryParam;
+    /**
+     * 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).
+     */
+    private redactUrl;
     private extractUTMParameters;
     private extractClickIdParameters;
     private extractReferralParameter;
@@ -27,6 +40,14 @@ declare class EventFactory implements IEventFactory {
      * first-touch referrer after a direct landing.
      */
     private getExternalReferrer;
+    /**
+     * 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.
+     */
+    private redactStoredTrafficSources;
     private getTrafficSources;
     private getScreen;
     private generateContext;

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

@@ -45,6 +45,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));
+};
 import { COUNTRY_LIST, LOCAL_ANONYMOUS_ID_KEY, SESSION_TRAFFIC_SOURCE_KEY, } from "../constants";
 import { toSnakeCase } from "../utils";
 import { validateAddress } from "../utils/address";
@@ -54,14 +63,14 @@ import { logger } from "../logger";
 import mergeDeepRight from "../ramda/mergeDeepRight";
 import { session } from "../storage";
 import { version } from "../version";
-import { CHANNEL, CLICK_ID_PARAMS, PAGE_PROPERTIES_EXCLUDED_FIELDS, VERSION, } from "./constants";
+import { CHANNEL, CLICK_ID_PARAMS, DEFAULT_EXCLUDED_QUERY_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;
-        var _a;
+        var _a, _b;
         this.extractUTMParameters = function (url) {
             var result = {
                 utm_campaign: "",
@@ -139,12 +148,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 = session().get(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(session().get(SESSION_TRAFFIC_SOURCE_KEY) || {});
             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];
@@ -185,8 +198,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 (isUndefined(pageProps.url)) {
-                pageProps.url = new URL(globalThis.location.href).href;
+                pageProps.url = urlObj ? urlObj.href : globalThis.location.href;
             }
             if (isUndefined(pageProps.path)) {
                 pageProps.path = globalThis.location.pathname;
@@ -196,18 +218,22 @@ var EventFactory = /** @class */ (function () {
             }
             // Add query string without the '?' prefix
             if (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 (isUndefined(pageProps[key]) && !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 (isUndefined(pageProps[key]) && !PAGE_PROPERTIES_EXCLUDED_FIELDS.has(key)) {
+                            pageProps[key] = value;
+                        }
+                    });
+                }
             }
             catch (error) {
                 logger.error("Error parsing query parameters for page properties:", error);
@@ -215,8 +241,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([], 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);
             }
@@ -278,6 +309,66 @@ var EventFactory = /** @class */ (function () {
     EventFactory.prototype.getLibraryVersion = function () {
         return 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 () {
@@ -306,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*/, detectBrowser()];
@@ -316,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 = mergeDeepRight(defaultContext, context || {});
                         return [2 /*return*/, mergedContext];
                 }

package/dist/esm/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/esm/src/event/constants.js

@@ -24,6 +24,22 @@ var CLICK_ID_PARAMS = [
     "rdt_cid", // Reddit Ads
     "ttclid", // TikTok Ads
 ];
+/**
+ * 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",
+];
 /**
  * Fields that should be excluded from page event properties parsing
  * These are either:
@@ -50,5 +66,5 @@ var PAGE_PROPERTIES_EXCLUDED_FIELDS = new Set(__spreadArray(__spreadArray([
     'hash',
     'query',
 ], false));
-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.js.map

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

@@ -72,6 +72,20 @@ export interface TrackingOptions {
     excludeHosts?: string[];
     excludePaths?: string[];
     excludeChains?: ChainID[];
+    /**
+     * 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