@formo/analytics 1.19.10 → 1.21.0

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/browser/browsers.d.ts

@@ -0,0 +1,3 @@
+export type BrowserName = "brave" | "chrome" | "edge" | "firefox" | "safari" | "opera" | "unknown";
+export declare function detectBrowser(): Promise<BrowserName>;
+//# sourceMappingURL=browsers.d.ts.map

package/dist/cjs/src/lib/browser/browsers.js

@@ -0,0 +1,132 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectBrowser = detectBrowser;
+var inFlight = null;
+var cached = null;
+function getUA() {
+    try {
+        return typeof globalThis.navigator !== "undefined"
+            ? globalThis.navigator.userAgent
+            : "";
+    }
+    catch (_a) {
+        return "";
+    }
+}
+function isBraveHeuristic() {
+    return __awaiter(this, void 0, void 0, function () {
+        var nav, ok, _a, brands;
+        var _b, _c;
+        return __generator(this, function (_d) {
+            switch (_d.label) {
+                case 0:
+                    nav = typeof globalThis.navigator !== "undefined"
+                        ? globalThis.navigator
+                        : undefined;
+                    if (!nav)
+                        return [2 /*return*/, false];
+                    _d.label = 1;
+                case 1:
+                    _d.trys.push([1, 4, , 5]);
+                    if (!((_b = nav.brave) === null || _b === void 0 ? void 0 : _b.isBrave)) return [3 /*break*/, 3];
+                    return [4 /*yield*/, nav.brave.isBrave().catch(function () { return false; })];
+                case 2:
+                    ok = _d.sent();
+                    if (ok)
+                        return [2 /*return*/, true];
+                    _d.label = 3;
+                case 3: return [3 /*break*/, 5];
+                case 4:
+                    _a = _d.sent();
+                    return [3 /*break*/, 5];
+                case 5:
+                    try {
+                        brands = (_c = nav.userAgentData) === null || _c === void 0 ? void 0 : _c.brands;
+                        if (brands === null || brands === void 0 ? void 0 : brands.some(function (b) { return /Brave/i.test(b.brand); }))
+                            return [2 /*return*/, true];
+                    }
+                    catch (_e) { }
+                    try {
+                        if (/Brave/i.test(nav.userAgent))
+                            return [2 /*return*/, true];
+                    }
+                    catch (_f) { }
+                    return [2 /*return*/, false];
+            }
+        });
+    });
+}
+function classifyNonBrave(ua) {
+    if (/Firefox\/\d+/i.test(ua))
+        return "firefox";
+    if (/Edg\/\d+/i.test(ua))
+        return "edge";
+    if (/OPR\/\d+/i.test(ua))
+        return "opera";
+    if (/Safari\/\d+/i.test(ua) && !/Chrome\/\d+/i.test(ua))
+        return "safari";
+    if (/Chrome\/\d+/i.test(ua))
+        return "chrome";
+    return "unknown";
+}
+function detectBrowser() {
+    var _this = this;
+    if (cached)
+        return Promise.resolve(cached);
+    if (inFlight)
+        return inFlight;
+    inFlight = (function () { return __awaiter(_this, void 0, void 0, function () {
+        var ua, brave;
+        return __generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    ua = getUA();
+                    return [4 /*yield*/, isBraveHeuristic().catch(function () { return false; })];
+                case 1:
+                    brave = _a.sent();
+                    cached = brave ? "brave" : classifyNonBrave(ua);
+                    return [2 /*return*/, cached];
+            }
+        });
+    }); })().finally(function () {
+        inFlight = null; // subsequent calls hit cache
+    });
+    return inFlight;
+}
+//# sourceMappingURL=browsers.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/EventFactory.d.ts

@@ -16,16 +16,16 @@ declare class EventFactory implements IEventFactory {
      */
     private getPageProperties;
     private getEnrichedEvent;
-    generatePageEvent(category?: string, name?: string, properties?: IFormoEventProperties, context?: IFormoEventContext): IFormoEvent;
-    generateDetectWalletEvent(providerName: string, rdns: string, properties?: IFormoEventProperties, context?: IFormoEventContext): IFormoEvent;
-    generateIdentifyEvent(providerName: string, rdns: string, address: Nullable<Address>, userId?: Nullable<string>, properties?: IFormoEventProperties, context?: IFormoEventContext): IFormoEvent;
-    generateConnectEvent(chainId: ChainID, address: Address, properties?: IFormoEventProperties, context?: IFormoEventContext): IFormoEvent;
-    generateDisconnectEvent(chainId?: ChainID, address?: Address, properties?: IFormoEventProperties, context?: IFormoEventContext): IFormoEvent;
-    generateChainChangedEvent(chainId: ChainID, address: Address, properties?: IFormoEventProperties, context?: IFormoEventContext): IFormoEvent;
-    generateSignatureEvent(status: SignatureStatus, chainId: ChainID, address: Address, message: string, signatureHash?: string, properties?: IFormoEventProperties, context?: IFormoEventContext): IFormoEvent;
-    generateTransactionEvent(status: TransactionStatus, chainId: ChainID, address: Address, data: string, to: string, value: string, transactionHash?: string, properties?: IFormoEventProperties, context?: IFormoEventContext): IFormoEvent;
-    generateTrackEvent(event: string, properties?: IFormoEventProperties, context?: IFormoEventContext): IFormoEvent;
-    create(event: APIEvent, address?: Address, userId?: string): IFormoEvent;
+    generatePageEvent(category?: string, name?: string, properties?: IFormoEventProperties, context?: IFormoEventContext): Promise<IFormoEvent>;
+    generateDetectWalletEvent(providerName: string, rdns: string, properties?: IFormoEventProperties, context?: IFormoEventContext): Promise<IFormoEvent>;
+    generateIdentifyEvent(providerName: string, rdns: string, address: Nullable<Address>, userId?: Nullable<string>, properties?: IFormoEventProperties, context?: IFormoEventContext): Promise<IFormoEvent>;
+    generateConnectEvent(chainId: ChainID, address: Address, properties?: IFormoEventProperties, context?: IFormoEventContext): Promise<IFormoEvent>;
+    generateDisconnectEvent(chainId?: ChainID, address?: Address, properties?: IFormoEventProperties, context?: IFormoEventContext): Promise<IFormoEvent>;
+    generateChainChangedEvent(chainId: ChainID, address: Address, properties?: IFormoEventProperties, context?: IFormoEventContext): Promise<IFormoEvent>;
+    generateSignatureEvent(status: SignatureStatus, chainId: ChainID, address: Address, message: string, signatureHash?: string, properties?: IFormoEventProperties, context?: IFormoEventContext): Promise<IFormoEvent>;
+    generateTransactionEvent(status: TransactionStatus, chainId: ChainID, address: Address, data: string, to: string, value: string, transactionHash?: string, properties?: IFormoEventProperties, context?: IFormoEventContext): Promise<IFormoEvent>;
+    generateTrackEvent(event: string, properties?: IFormoEventProperties, context?: IFormoEventContext): Promise<IFormoEvent>;
+    create(event: APIEvent, address?: Address, userId?: string): Promise<IFormoEvent>;
 }
 export { EventFactory };
 //# sourceMappingURL=EventFactory.d.ts.map