@formo/analytics 1.19.10 → 1.20.0

package/dist/esm/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/esm/src/lib/consent.js

@@ -0,0 +1,97 @@
+/**
+ * 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.
+ */
+import { secureHash } from '../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(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
+ */
+export 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
+ */
+export 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
+ */
+export 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/esm/src/lib/event/EventManager.js

@@ -11,6 +11,7 @@ var __rest = (this && this.__rest) || function (s, e) {
 };
 import { logger } from "../logger";
 import { EventFactory } from "./EventFactory";
+import { isBlockedAddress } from "../../utils/address";
 /**
  * A service to generate valid event payloads and queue them for processing
  */
@@ -30,6 +31,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 && isBlockedAddress(formoEvent.address)) {
+            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.error("Error sending events:", err);

package/dist/esm/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/esm/src/lib/index.js

@@ -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.js.map

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

@@ -1,10 +1,11 @@
 import { KEY_PREFIX } from "../constant";
+import { secureHash } from "../../../utils/hash";
 var StorageBlueprint = /** @class */ (function () {
     function StorageBlueprint(writeKey) {
         this.writeKey = writeKey;
     }
     StorageBlueprint.prototype.getKey = function (key) {
-        return "".concat(KEY_PREFIX, "_").concat(this.writeKey, ".").concat(key);
+        return "".concat(KEY_PREFIX, "_").concat(secureHash(this.writeKey), "_").concat(key);
     };
     return StorageBlueprint;
 }());

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

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

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

@@ -1,3 +1,3 @@
 // Generated by genversion.
-export var version = '1.19.10';
+export var version = '1.20.0';
 //# sourceMappingURL=version.js.map

package/dist/esm/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/esm/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/esm/src/utils/address.js

@@ -2,6 +2,7 @@ import { keccak256 } from "ethereum-cryptography/keccak.js";
 import { utf8ToBytes } from "ethereum-cryptography/utils.js";
 import { ensureIfUint8Array, isAddress, uint8ArrayToHexString, } from "../validators";
 import { isNullish } from "../validators/object";
+import { BLOCKED_ADDRESSES } from "../constants";
 /**
  * Private helper function to validate and trim an address
  * @param address The address to validate and trim
@@ -36,6 +37,24 @@ export var isValidAddress = function (address) {
 export var getValidAddress = function (address) {
     return _validateAndTrimAddress(address);
 };
+/**
+ * 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 var isBlockedAddress = function (address) {
+    if (!address)
+        return false;
+    var validAddress = getValidAddress(address);
+    if (!validAddress)
+        return false;
+    // Normalize to checksum format for comparison
+    var checksumAddress = toChecksumAddress(validAddress);
+    return BLOCKED_ADDRESSES.some(function (blockedAddr) {
+        return toChecksumAddress(blockedAddr) === checksumAddress;
+    });
+};
 export var toChecksumAddress = function (address) {
     if (!isAddress(address, false)) {
         throw new Error("Invalid address " + address);

package/dist/esm/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/esm/src/utils/hash.js

@@ -0,0 +1,18 @@
+/**
+ * Hash utilities using ethereum-cryptography for secure, deterministic hashing
+ */
+import { sha256 } from 'ethereum-cryptography/sha256';
+import { utf8ToBytes, bytesToHex } from '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)
+ */
+export function secureHash(str) {
+    var bytes = utf8ToBytes(str);
+    var hashBytes = sha256(bytes);
+    var hashHex = bytesToHex(hashBytes);
+    // Return first 8 characters for reasonable cookie name length
+    return hashHex.slice(0, 8);
+}
+//# sourceMappingURL=hash.js.map

package/dist/esm/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/esm/src/utils/index.js

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