@formo/analytics 1.19.9 → 1.20.0

package/README.md

@@ -24,7 +24,9 @@ You can install Formo on:
 - [React apps](https://docs.formo.so/install#react)
 - [Next.js apps](https://docs.formo.so/install#next-js-app-router)
 
-Visit Formo's [Developer Docs](https://docs.formo.so) for detailed guides and installation instructions.
+## Configuration
+
+Visit Formo's [Developer Docs](https://docs.formo.so) for detailed guides on local testing, debugging, and consent management.
 
 ## Methodology
 

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

@@ -177,6 +177,22 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @returns {Promise<void>}
      */
     track(event: string, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
+    /**
+     * Opt out of tracking.
+     * @returns {void}
+     */
+    optOutTracking(): void;
+    /**
+     * Opt back into tracking after previously opting out. This will re-enable analytics tracking
+     * and switch back to persistent storage.
+     * @returns {void}
+     */
+    optInTracking(): void;
+    /**
+     * Check if the user has opted out of tracking.
+     * @returns {boolean} True if the user has opted out
+     */
+    hasOptedOutTracking(): boolean;
     private trackProvider;
     private trackProviders;
     private addProviderListener;
@@ -204,7 +220,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private trackPageHit;
     private trackEvent;
     /**
-     * Determines if tracking should be enabled based on configuration
+     * Determines if tracking should be enabled based on configuration and consent
      * @returns {boolean} True if tracking should be enabled
      */
     private shouldTrack;

package/dist/cjs/src/FormoAnalytics.js

@@ -126,6 +126,10 @@ var FormoAnalytics = /** @class */ (function () {
             maxQueueSize: options.maxQueueSize,
             flushInterval: options.flushInterval,
         }));
+        // Check consent status on initialization
+        if (this.hasOptedOutTracking()) {
+            lib_1.logger.info("User has previously opted out of tracking");
+        }
         // Handle initial provider (injected) as fallback; listeners for EIP-6963 are added later
         var provider = undefined;
         var optProvider = options.provider;
@@ -407,7 +411,7 @@ var FormoAnalytics = /** @class */ (function () {
      */
     FormoAnalytics.prototype.identify = function (params, properties, context, callback) {
         return __awaiter(this, void 0, void 0, function () {
-            var _i, _a, providerDetail, provider, address_2, validAddress_1, err_1, userId, address, providerName, rdns, validAddress, e_1;
+            var _i, _a, providerDetail, provider, address_2, validAddress_1, err_1, userId, address, providerName, rdns, validAddress, isAlreadyIdentified, e_1;
             var _b;
             return __generator(this, function (_c) {
                 switch (_c.label) {
@@ -432,6 +436,12 @@ var FormoAnalytics = /** @class */ (function () {
                         address_2 = _c.sent();
                         if (!address_2) return [3 /*break*/, 6];
                         validAddress_1 = this.validateAndChecksumAddress(address_2);
+                        lib_1.logger.info("Auto-identify: Checking deduplication", {
+                            validAddress: validAddress_1,
+                            rdns: providerDetail.info.rdns,
+                            providerName: providerDetail.info.name,
+                            isAlreadyIdentified: validAddress_1 ? this.session.isWalletIdentified(validAddress_1, providerDetail.info.rdns) : false
+                        });
                         if (!(validAddress_1 && !this.session.isWalletIdentified(validAddress_1, providerDetail.info.rdns))) return [3 /*break*/, 5];
                         lib_1.logger.info("Auto-identifying", validAddress_1, providerDetail.info.name, providerDetail.info.rdns);
                         // NOTE: do not set this.currentAddress without explicit connect or identify
@@ -476,14 +486,23 @@ var FormoAnalytics = /** @class */ (function () {
                             this.currentUserId = userId;
                             (0, lib_1.cookie)().set(constants_1.SESSION_USER_ID_KEY, userId);
                         }
-                        // Check for duplicate identify events in this session
-                        if (validAddress && rdns && this.session.isWalletIdentified(validAddress, rdns)) {
-                            lib_1.logger.warn("Identify: Wallet ".concat(providerName || 'Unknown', " with address ").concat(validAddress, " already identified in this session"));
+                        isAlreadyIdentified = validAddress ? this.session.isWalletIdentified(validAddress, rdns || '') : false;
+                        lib_1.logger.debug("Identify: Checking deduplication", {
+                            validAddress: validAddress,
+                            rdns: rdns,
+                            providerName: providerName,
+                            hasValidAddress: !!validAddress,
+                            hasRdns: !!rdns,
+                            isAlreadyIdentified: isAlreadyIdentified
+                        });
+                        if (isAlreadyIdentified) {
+                            lib_1.logger.info("Identify: Wallet ".concat(providerName || 'Unknown', " with address ").concat(validAddress, " already identified in this session (rdns: ").concat(rdns || 'empty', ")"));
                             return [2 /*return*/];
                         }
                         // Mark as identified before emitting the event
-                        if (validAddress && rdns) {
-                            this.session.markWalletIdentified(validAddress, rdns);
+                        // Mark even if rdns is empty to prevent duplicate empty identifies
+                        if (validAddress) {
+                            this.session.markWalletIdentified(validAddress, rdns || '');
                         }
                         return [4 /*yield*/, this.trackEvent(constants_1.EventType.IDENTIFY, {
                                 address: validAddress,
@@ -552,6 +571,39 @@ var FormoAnalytics = /** @class */ (function () {
             });
         });
     };
+    /*
+      Consent management functions
+    */
+    /**
+     * Opt out of tracking.
+     * @returns {void}
+     */
+    FormoAnalytics.prototype.optOutTracking = function () {
+        lib_1.logger.info("Opting out of tracking");
+        // Set opt-out flag in persistent storage using direct cookie access
+        // This must be done before switching storage to ensure persistence
+        (0, lib_1.setConsentFlag)(this.writeKey, constants_1.CONSENT_OPT_OUT_KEY, "true");
+        this.reset();
+        lib_1.logger.info("Successfully opted out of tracking");
+    };
+    /**
+     * Opt back into tracking after previously opting out. This will re-enable analytics tracking
+     * and switch back to persistent storage.
+     * @returns {void}
+     */
+    FormoAnalytics.prototype.optInTracking = function () {
+        lib_1.logger.info("Opting back into tracking");
+        // Remove opt-out flag
+        (0, lib_1.removeConsentFlag)(this.writeKey, constants_1.CONSENT_OPT_OUT_KEY);
+        lib_1.logger.info("Successfully opted back into tracking");
+    };
+    /**
+     * Check if the user has opted out of tracking.
+     * @returns {boolean} True if the user has opted out
+     */
+    FormoAnalytics.prototype.hasOptedOutTracking = function () {
+        return (0, lib_1.getConsentFlag)(this.writeKey, constants_1.CONSENT_OPT_OUT_KEY) === "true";
+    };
     /*
       SDK tracking and event listener functions
     */
@@ -1262,10 +1314,14 @@ var FormoAnalytics = /** @class */ (function () {
         });
     };
     /**
-     * Determines if tracking should be enabled based on configuration
+     * Determines if tracking should be enabled based on configuration and consent
      * @returns {boolean} True if tracking should be enabled
      */
     FormoAnalytics.prototype.shouldTrack = function () {
+        // First check if user has opted out of tracking
+        if (this.hasOptedOutTracking()) {
+            return false;
+        }
         // Check if tracking is explicitly provided as a boolean
         if (typeof this.options.tracking === 'boolean') {
             return this.options.tracking;
@@ -1847,6 +1903,10 @@ exports.FormoAnalytics = FormoAnalytics;
 var FormoAnalyticsSession = /** @class */ (function () {
     function FormoAnalyticsSession() {
     }
+    FormoAnalyticsSession.prototype.generateIdentificationKey = function (address, rdns) {
+        // If rdns is missing, use address-only key as fallback for empty identifies
+        return rdns ? "".concat(address, ":").concat(rdns) : address;
+    };
     FormoAnalyticsSession.prototype.isWalletDetected = function (rdns) {
         var _a;
         var rdnses = ((_a = (0, lib_1.cookie)().get(constants_1.SESSION_WALLET_DETECTED_KEY)) === null || _a === void 0 ? void 0 : _a.split(",")) || [];
@@ -1865,22 +1925,40 @@ var FormoAnalyticsSession = /** @class */ (function () {
         }
     };
     FormoAnalyticsSession.prototype.isWalletIdentified = function (address, rdns) {
-        var _a;
-        var identifiedKey = "".concat(address, ":").concat(rdns);
-        var identifiedWallets = ((_a = (0, lib_1.cookie)().get(constants_1.SESSION_WALLET_IDENTIFIED_KEY)) === null || _a === void 0 ? void 0 : _a.split(",")) || [];
-        return identifiedWallets.includes(identifiedKey);
+        var identifiedKey = this.generateIdentificationKey(address, rdns);
+        var cookieValue = (0, lib_1.cookie)().get(constants_1.SESSION_WALLET_IDENTIFIED_KEY);
+        var identifiedWallets = (cookieValue === null || cookieValue === void 0 ? void 0 : cookieValue.split(",")) || [];
+        var isIdentified = identifiedWallets.includes(identifiedKey);
+        lib_1.logger.debug("Session: Checking wallet identification", {
+            identifiedKey: identifiedKey,
+            isIdentified: isIdentified,
+            hasRdns: !!rdns
+        });
+        return isIdentified;
     };
     FormoAnalyticsSession.prototype.markWalletIdentified = function (address, rdns) {
         var _a;
-        var identifiedKey = "".concat(address, ":").concat(rdns);
+        var identifiedKey = this.generateIdentificationKey(address, rdns);
         var identifiedWallets = ((_a = (0, lib_1.cookie)().get(constants_1.SESSION_WALLET_IDENTIFIED_KEY)) === null || _a === void 0 ? void 0 : _a.split(",")) || [];
         if (!identifiedWallets.includes(identifiedKey)) {
             identifiedWallets.push(identifiedKey);
-            (0, lib_1.cookie)().set(constants_1.SESSION_WALLET_IDENTIFIED_KEY, identifiedWallets.join(","), {
+            var newValue = identifiedWallets.join(",");
+            (0, lib_1.cookie)().set(constants_1.SESSION_WALLET_IDENTIFIED_KEY, newValue, {
                 // by the end of the day
                 expires: new Date(Date.now() + 86400 * 1000).toUTCString(),
                 path: "/",
             });
+            lib_1.logger.debug("Session: Marked wallet as identified", {
+                identifiedKey: identifiedKey,
+                hasRdns: !!rdns
+            });
+        }
+        else {
+            lib_1.logger.info("Session: Wallet already marked as identified", {
+                identifiedKey: identifiedKey,
+                existingWallets: identifiedWallets,
+                hasRdns: !!rdns
+            });
         }
     };
     return FormoAnalyticsSession;

package/dist/cjs/src/FormoAnalyticsProvider.js

@@ -55,7 +55,7 @@ var lib_1 = require("./lib");
 var defaultContext = {
     chain: function () { return Promise.resolve(); },
     page: function () { return Promise.resolve(); },
-    reset: function () { return Promise.resolve(); },
+    reset: function () { },
     detect: function () { return Promise.resolve(); },
     connect: function () { return Promise.resolve(); },
     disconnect: function () { return Promise.resolve(); },
@@ -63,6 +63,10 @@ var defaultContext = {
     transaction: function () { return Promise.resolve(); },
     identify: function () { return Promise.resolve(); },
     track: function () { return Promise.resolve(); },
+    // Consent management methods
+    optOutTracking: function () { },
+    optInTracking: function () { },
+    hasOptedOutTracking: function () { return false; },
 };
 exports.FormoAnalyticsContext = (0, react_1.createContext)(defaultContext);
 var FormoAnalyticsProvider = function (props) {

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

@@ -4,5 +4,9 @@ export declare const SESSION_WALLET_IDENTIFIED_KEY = "wallet-identified";
 export declare const SESSION_CURRENT_URL_KEY = "analytics-current-url";
 export declare const SESSION_USER_ID_KEY = "user-id";
 export declare const LOCAL_ANONYMOUS_ID_KEY = "anonymous-id";
+export declare const CONSENT_OPT_OUT_KEY = "opt-out-tracking";
 export declare const DEFAULT_PROVIDER_ICON = "data:image/svg+xml;base64,";
+export declare const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+export declare const DEAD_ADDRESS = "0x000000000000000000000000000000000000dEaD";
+export declare const BLOCKED_ADDRESSES: readonly ["0x0000000000000000000000000000000000000000", "0x000000000000000000000000000000000000dEaD"];
 //# sourceMappingURL=base.d.ts.map

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

@@ -1,12 +1,19 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_PROVIDER_ICON = exports.LOCAL_ANONYMOUS_ID_KEY = exports.SESSION_USER_ID_KEY = exports.SESSION_CURRENT_URL_KEY = exports.SESSION_WALLET_IDENTIFIED_KEY = exports.SESSION_WALLET_DETECTED_KEY = exports.SESSION_TRAFFIC_SOURCE_KEY = void 0;
+exports.BLOCKED_ADDRESSES = exports.DEAD_ADDRESS = exports.ZERO_ADDRESS = exports.DEFAULT_PROVIDER_ICON = exports.CONSENT_OPT_OUT_KEY = exports.LOCAL_ANONYMOUS_ID_KEY = exports.SESSION_USER_ID_KEY = exports.SESSION_CURRENT_URL_KEY = exports.SESSION_WALLET_IDENTIFIED_KEY = exports.SESSION_WALLET_DETECTED_KEY = exports.SESSION_TRAFFIC_SOURCE_KEY = void 0;
 exports.SESSION_TRAFFIC_SOURCE_KEY = "traffic-source";
 exports.SESSION_WALLET_DETECTED_KEY = "wallet-detected";
 exports.SESSION_WALLET_IDENTIFIED_KEY = "wallet-identified";
 exports.SESSION_CURRENT_URL_KEY = "analytics-current-url";
 exports.SESSION_USER_ID_KEY = "user-id";
 exports.LOCAL_ANONYMOUS_ID_KEY = "anonymous-id";
+// Consent management keys
+exports.CONSENT_OPT_OUT_KEY = "opt-out-tracking";
 // Default provider icon (empty data URL)
 exports.DEFAULT_PROVIDER_ICON = 'data:image/svg+xml;base64,';
+// Blocked addresses that should not emit events
+exports.ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+exports.DEAD_ADDRESS = "0x000000000000000000000000000000000000dEaD";
+// Array of all blocked addresses for easy checking
+exports.BLOCKED_ADDRESSES = [exports.ZERO_ADDRESS, exports.DEAD_ADDRESS];
 //# sourceMappingURL=base.js.map

package/dist/cjs/src/lib/consent.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Consent management utilities for handling tracking consent flags in cookies.
+ * These functions bypass the consent-aware storage system to ensure consent
+ * preferences are always stored persistently for compliance purposes.
+ *
+ * All consent cookies are project-specific to avoid conflicts between different
+ * Formo projects on the same domain.
+ */
+/**
+ * Set a consent flag directly in cookies, bypassing the consent-aware storage system.
+ * Uses cookies for consent storage to ensure:
+ * - Cross-domain/subdomain compatibility
+ * - Server-side accessibility for compliance auditing
+ * - Regulatory compliance (GDPR/CCPA requirements)
+ * - Explicit expiration handling
+ * - Project isolation (no conflicts between different Formo projects)
+ * @param projectId - The project identifier (writeKey)
+ * @param key - The cookie key
+ * @param value - The cookie value
+ */
+export declare function setConsentFlag(projectId: string, key: string, value: string): void;
+/**
+ * Get a consent flag directly from cookies, bypassing the consent-aware storage system
+ * @param projectId - The project identifier (writeKey)
+ * @param key - The cookie key
+ * @returns The cookie value or null if not found
+ */
+export declare function getConsentFlag(projectId: string, key: string): string | null;
+/**
+ * Remove a consent flag directly from cookies, bypassing the consent-aware storage system
+ * @param projectId - The project identifier (writeKey)
+ * @param key - The cookie key
+ */
+export declare function removeConsentFlag(projectId: string, key: string): void;
+//# sourceMappingURL=consent.d.ts.map

package/dist/cjs/src/lib/consent.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Consent management utilities for handling tracking consent flags in cookies.
+ * These functions bypass the consent-aware storage system to ensure consent
+ * preferences are always stored persistently for compliance purposes.
+ *
+ * All consent cookies are project-specific to avoid conflicts between different
+ * Formo projects on the same domain.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setConsentFlag = setConsentFlag;
+exports.getConsentFlag = getConsentFlag;
+exports.removeConsentFlag = removeConsentFlag;
+var hash_1 = require("../utils/hash");
+/**
+ * Generate a project-specific cookie key to avoid conflicts between different Formo projects
+ * Uses hashed writeKey for privacy and security
+ * @param projectId - The project identifier (writeKey)
+ * @param key - The base cookie key
+ * @returns Project-specific cookie key
+ */
+function getProjectSpecificKey(projectId, key) {
+    return "formo_".concat((0, hash_1.secureHash)(projectId), "_").concat(key);
+}
+/**
+ * Set a consent flag directly in cookies, bypassing the consent-aware storage system.
+ * Uses cookies for consent storage to ensure:
+ * - Cross-domain/subdomain compatibility
+ * - Server-side accessibility for compliance auditing
+ * - Regulatory compliance (GDPR/CCPA requirements)
+ * - Explicit expiration handling
+ * - Project isolation (no conflicts between different Formo projects)
+ * @param projectId - The project identifier (writeKey)
+ * @param key - The cookie key
+ * @param value - The cookie value
+ */
+function setConsentFlag(projectId, key, value) {
+    var _a;
+    if (typeof document !== 'undefined') {
+        var projectSpecificKey = getProjectSpecificKey(projectId, key);
+        var expires = new Date(Date.now() + 365 * 24 * 60 * 60 * 1000).toUTCString(); // 1 year (GDPR compliant)
+        var isSecure = ((_a = window === null || window === void 0 ? void 0 : window.location) === null || _a === void 0 ? void 0 : _a.protocol) === 'https:';
+        // Enhanced privacy settings: Secure (HTTPS), SameSite=Strict for consent cookies
+        document.cookie = "".concat(projectSpecificKey, "=").concat(encodeURIComponent(value), "; expires=").concat(expires, "; path=/; SameSite=Strict").concat(isSecure ? '; Secure' : '');
+    }
+}
+/**
+ * Get a consent flag directly from cookies, bypassing the consent-aware storage system
+ * @param projectId - The project identifier (writeKey)
+ * @param key - The cookie key
+ * @returns The cookie value or null if not found
+ */
+function getConsentFlag(projectId, key) {
+    if (typeof document === 'undefined')
+        return null;
+    var projectSpecificKey = getProjectSpecificKey(projectId, key);
+    var cookies = document.cookie.split(';');
+    for (var _i = 0, cookies_1 = cookies; _i < cookies_1.length; _i++) {
+        var cookie = cookies_1[_i];
+        var trimmed = cookie.trim();
+        var eqIdx = trimmed.indexOf('=');
+        if (eqIdx === -1)
+            continue;
+        var cookieKey = trimmed.substring(0, eqIdx);
+        var cookieValue = trimmed.substring(eqIdx + 1);
+        if (cookieKey === projectSpecificKey) {
+            return decodeURIComponent(cookieValue || '');
+        }
+    }
+    return null;
+}
+/**
+ * Remove a consent flag directly from cookies, bypassing the consent-aware storage system
+ * @param projectId - The project identifier (writeKey)
+ * @param key - The cookie key
+ */
+function removeConsentFlag(projectId, key) {
+    var projectSpecificKey = getProjectSpecificKey(projectId, key);
+    deleteCookieDirectly(projectSpecificKey);
+}
+/**
+ * Delete a cookie directly, handling various domain scenarios
+ * @param cookieName - The name of the cookie to delete
+ */
+function deleteCookieDirectly(cookieName) {
+    if (typeof document === 'undefined')
+        return;
+    // Clear from current domain/path
+    document.cookie = "".concat(cookieName, "=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/;");
+    // Try to clear from parent domain if it's a proper multi-level domain
+    if (typeof window !== 'undefined') {
+        var hostname = window.location.hostname;
+        var parts = hostname.split('.');
+        // Only try parent domain deletion for proper domains with multiple parts
+        // Skip localhost and single-level domains
+        if (parts.length >= 2 && hostname !== 'localhost') {
+            var domain = parts.slice(-2).join('.');
+            document.cookie = "".concat(cookieName, "=; expires=Thu, 01 Jan 1970 00:00:00 UTC; path=/; domain=.").concat(domain, ";");
+        }
+    }
+}
+//# sourceMappingURL=consent.js.map

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

@@ -14,6 +14,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EventManager = void 0;
 var logger_1 = require("../logger");
 var EventFactory_1 = require("./EventFactory");
+var address_1 = require("../../utils/address");
 /**
  * A service to generate valid event payloads and queue them for processing
  */
@@ -33,6 +34,11 @@ var EventManager = /** @class */ (function () {
     EventManager.prototype.addEvent = function (event, address, userId) {
         var callback = event.callback, _event = __rest(event, ["callback"]);
         var formoEvent = this.eventFactory.create(_event, address, userId);
+        // Check if the final event has a blocked address - don't queue it
+        if (formoEvent.address && (0, address_1.isBlockedAddress)(formoEvent.address)) {
+            logger_1.logger.warn("Event blocked: Address ".concat(formoEvent.address, " is in the blocked list and cannot emit events"));
+            return;
+        }
         this.eventQueue.enqueue(formoEvent, function (err, _, data) {
             if (err) {
                 logger_1.logger.error("Error sending events:", err);

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

@@ -2,5 +2,6 @@ export * from "./event";
 export * from "./logger";
 export * from "./queue";
 export * from "./storage";
+export * from "./consent";
 export { default as fetch } from "./fetch";
 //# sourceMappingURL=index.d.ts.map

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

@@ -22,6 +22,7 @@ __exportStar(require("./event"), exports);
 __exportStar(require("./logger"), exports);
 __exportStar(require("./queue"), exports);
 __exportStar(require("./storage"), exports);
+__exportStar(require("./consent"), exports);
 var fetch_1 = require("./fetch");
 Object.defineProperty(exports, "fetch", { enumerable: true, get: function () { return __importDefault(fetch_1).default; } });
 //# sourceMappingURL=index.js.map

package/dist/cjs/src/lib/storage/built-in/blueprint.js

@@ -1,12 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 var constant_1 = require("../constant");
+var hash_1 = require("../../../utils/hash");
 var StorageBlueprint = /** @class */ (function () {
     function StorageBlueprint(writeKey) {
         this.writeKey = writeKey;
     }
     StorageBlueprint.prototype.getKey = function (key) {
-        return "".concat(constant_1.KEY_PREFIX, "_").concat(this.writeKey, ".").concat(key);
+        return "".concat(constant_1.KEY_PREFIX, "_").concat((0, hash_1.secureHash)(this.writeKey), "_").concat(key);
     };
     return StorageBlueprint;
 }());

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

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

package/dist/cjs/src/lib/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // Generated by genversion.
-exports.version = '1.19.7';
+exports.version = '1.20.0';
 //# sourceMappingURL=version.js.map

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

@@ -48,6 +48,9 @@ export interface IFormoAnalytics {
         rdns?: string;
     }, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
     track(event: string, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
+    optOutTracking(): void;
+    optInTracking(): void;
+    hasOptedOutTracking(): boolean;
 }
 export interface Config {
     writeKey: string;

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

@@ -18,5 +18,12 @@ export declare const isValidAddress: (address: Address | null | undefined) => ad
  * This function is the preferred way to get a validated, trimmed address for use in your application.
  */
 export declare const getValidAddress: (address: Address | null | undefined) => string | null;
+/**
+ * Checks if an address is in the blocked list and should not emit events.
+ * Blocked addresses include the zero address and dead address which are not normal user addresses.
+ * @param address The address to check
+ * @returns true if the address is blocked, false otherwise
+ */
+export declare const isBlockedAddress: (address: Address | null | undefined) => boolean;
 export declare const toChecksumAddress: (address: Address) => string;
 //# sourceMappingURL=address.d.ts.map

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

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toChecksumAddress = exports.getValidAddress = exports.isValidAddress = void 0;
+exports.toChecksumAddress = exports.isBlockedAddress = exports.getValidAddress = exports.isValidAddress = void 0;
 var keccak_js_1 = require("ethereum-cryptography/keccak.js");
 var utils_js_1 = require("ethereum-cryptography/utils.js");
 var validators_1 = require("../validators");
 var object_1 = require("../validators/object");
+var constants_1 = require("../constants");
 /**
  * Private helper function to validate and trim an address
  * @param address The address to validate and trim
@@ -41,6 +42,25 @@ var getValidAddress = function (address) {
     return _validateAndTrimAddress(address);
 };
 exports.getValidAddress = getValidAddress;
+/**
+ * Checks if an address is in the blocked list and should not emit events.
+ * Blocked addresses include the zero address and dead address which are not normal user addresses.
+ * @param address The address to check
+ * @returns true if the address is blocked, false otherwise
+ */
+var isBlockedAddress = function (address) {
+    if (!address)
+        return false;
+    var validAddress = (0, exports.getValidAddress)(address);
+    if (!validAddress)
+        return false;
+    // Normalize to checksum format for comparison
+    var checksumAddress = (0, exports.toChecksumAddress)(validAddress);
+    return constants_1.BLOCKED_ADDRESSES.some(function (blockedAddr) {
+        return (0, exports.toChecksumAddress)(blockedAddr) === checksumAddress;
+    });
+};
+exports.isBlockedAddress = isBlockedAddress;
 var toChecksumAddress = function (address) {
     if (!(0, validators_1.isAddress)(address, false)) {
         throw new Error("Invalid address " + address);

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

@@ -0,0 +1,10 @@
+/**
+ * Hash utilities using ethereum-cryptography for secure, deterministic hashing
+ */
+/**
+ * Generate a secure hash of a string using SHA-256 for creating short, consistent identifiers
+ * @param str - The string to hash
+ * @returns Short hash string (first 8 characters of SHA-256 hex)
+ */
+export declare function secureHash(str: string): string;
+//# sourceMappingURL=hash.d.ts.map

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

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Hash utilities using ethereum-cryptography for secure, deterministic hashing
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secureHash = secureHash;
+var sha256_1 = require("ethereum-cryptography/sha256");
+var utils_1 = require("ethereum-cryptography/utils");
+/**
+ * Generate a secure hash of a string using SHA-256 for creating short, consistent identifiers
+ * @param str - The string to hash
+ * @returns Short hash string (first 8 characters of SHA-256 hex)
+ */
+function secureHash(str) {
+    var bytes = (0, utils_1.utf8ToBytes)(str);
+    var hashBytes = (0, sha256_1.sha256)(bytes);
+    var hashHex = (0, utils_1.bytesToHex)(hashBytes);
+    // Return first 8 characters for reasonable cookie name length
+    return hashHex.slice(0, 8);
+}
+//# sourceMappingURL=hash.js.map

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

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

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

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

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

@@ -177,6 +177,22 @@ export declare class FormoAnalytics implements IFormoAnalytics {
      * @returns {Promise<void>}
      */
     track(event: string, properties?: IFormoEventProperties, context?: IFormoEventContext, callback?: (...args: unknown[]) => void): Promise<void>;
+    /**
+     * Opt out of tracking.
+     * @returns {void}
+     */
+    optOutTracking(): void;
+    /**
+     * Opt back into tracking after previously opting out. This will re-enable analytics tracking
+     * and switch back to persistent storage.
+     * @returns {void}
+     */
+    optInTracking(): void;
+    /**
+     * Check if the user has opted out of tracking.
+     * @returns {boolean} True if the user has opted out
+     */
+    hasOptedOutTracking(): boolean;
     private trackProvider;
     private trackProviders;
     private addProviderListener;
@@ -204,7 +220,7 @@ export declare class FormoAnalytics implements IFormoAnalytics {
     private trackPageHit;
     private trackEvent;
     /**
-     * Determines if tracking should be enabled based on configuration
+     * Determines if tracking should be enabled based on configuration and consent
      * @returns {boolean} True if tracking should be enabled
      */
     private shouldTrack;