utmtrack.js

/**
 * UTMTrackJS - Biblioteca para capturar, armazenar e preencher automaticamente parâmetros UTM
 * @version 0.9.5
 * @author Gabriel Masson
 * @license MIT
 * @repo https://github.com/gmasson/utmtrackjs
 */

((window) => {
	'use strict';

	// Verificações de compatibilidade do ambiente
	if (typeof window === 'undefined' || typeof document === 'undefined') {
		console.warn('UTMTrackJS: Esta biblioteca só funciona em ambiente de navegador.');
		return;
	}

	if (typeof Storage === 'undefined') {
		console.warn('UTMTrackJS: localStorage não está disponível neste navegador.');
		return;
	}

	// Constantes da aplicação
	const CONSTANTS = Object.freeze({
		STORAGE_KEY: 'utmtrackjs_last_params',
		VERSION: '0.9.5',
		MAX_UTM_LENGTH: 500,
		MAX_KEY_LENGTH: 50,
		MAX_KEYS: 50,
		MAX_PARAMS: 50,
		MAX_STORAGE_SIZE: 50000, // 50KB
		MAX_URL_LENGTH: 2048,
		DEFAULT_MAX_DATA_AGE: 7 * 24 * 60 * 60 * 1000, // 7 dias
		THROTTLE_DELAY: 50, // ms
		ALLOWED_EVENTS: ['input', 'change', 'focus', 'blur'],
		ALLOWED_INPUT_TYPES: ['text', 'hidden', 'search', 'url', 'tel', 'email'],
		FORM_ELEMENTS: ['input', 'textarea', 'select'],
		CUSTOM_EVENTS: {
			UTM_CAPTURED: 'utmtrackjs:captured',
			UTM_UPDATED: 'utmtrackjs:updated',
			UTM_REMOVED: 'utmtrackjs:removed',
			CONFIG_CHANGED: 'utmtrackjs:configChanged'
		}
	});

	// Parâmetros UTM suportados
	const DEFAULT_UTM_KEYS = Object.freeze([
		// UTM padrão
		'utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content', 'utm_id',
		// UTM estendido
		'utm_source_platform', 'utm_creative_format', 'utm_marketing_tactic',
		// Click IDs de plataformas
		'gclid', 'fbclid', 'msclkid', 'ttclid', 'twclid', 'li_fat_id',
		// Salesforce Campaign
		'sc_campaign', 'sc_channel', 'sc_content', 'sc_medium', 'sc_outcome',
		// MailChimp
		'mc_cid', 'mc_eid',
		// Piwik/Matomo
		'pk_campaign', 'pk_kwd', 'pk_medium', 'pk_source'
	]);

	// Estado global da aplicação
	const AppState = (() => {
		const state = {
			config: {
				updateWithLatest: true,
				customUtmKeys: null,
				maxDataAge: CONSTANTS.DEFAULT_MAX_DATA_AGE,
				loggingEnabled: true
			},
			runtime: {
				domContentLoadedListenerAdded: false,
				urlChangeListenerAdded: false,
				lastUrl: '',
				isInitialized: false,
				originalHistory: null,
				urlListenersBound: false,
				eventListeners: new Set()
			}
		};
		
		return Object.seal(state);
	})();

	// Verifica configuração pré-definida pelo usuário
	if (typeof window.UTMTrackJSConfig === 'object' && window.UTMTrackJSConfig !== null) {
		if (typeof window.UTMTrackJSConfig.updateWithLatest === 'boolean') {
			AppState.config.updateWithLatest = window.UTMTrackJSConfig.updateWithLatest;
		}
		if (typeof window.UTMTrackJSConfig.maxDataAge === 'number' || window.UTMTrackJSConfig.maxDataAge === false) {
			AppState.config.maxDataAge = window.UTMTrackJSConfig.maxDataAge;
		}
		if (Array.isArray(window.UTMTrackJSConfig.customUtmKeys)) {
			AppState.config.customUtmKeys = window.UTMTrackJSConfig.customUtmKeys;
		}
	}

	// Classes de erro e resultado
	class UTMTrackError extends Error {
		constructor(message, code = 'GENERAL') {
			super(message);
			this.name = 'UTMTrackError';
			this.code = code;
		}
	}

	class UTMResult {
		constructor(success, data = null, error = null) {
			this.success = success;
			this.data = data;
			this.error = error;
		}

		static success(data = null) {
			return new UTMResult(true, data, null);
		}

		static failure(error) {
			return new UTMResult(false, null, error);
		}
	}

	// Módulo de validação e sanitização
	const ValidationModule = {
		/**
		 * Valida chave UTM
		 * @param {string} key - Chave UTM
		 * @returns {boolean} True se válida
		 */
		isValidUtmKey(key) {
			if (typeof key !== 'string' || !key.trim()) {
				return false;
			}
			const trimmed = key.trim();
			if (trimmed.length > CONSTANTS.MAX_KEY_LENGTH) {
				return false;
			}
			return /^[a-zA-Z0-9_]+$/.test(trimmed);
		},

		/**
		 * Sanitiza valor UTM usando whitelist de caracteres seguros
		 * @param {any} value - Valor a ser sanitizado
		 * @returns {string|null} Valor sanitizado ou null se inválido
		 */
		sanitizeUtmValue(value) {
			if (value === null || value === undefined) {
				return null;
			}

			let sanitized = String(value).trim();

			// Whitelist: letras, números, hífen, underscore, ponto, espaço
			sanitized = sanitized.replace(/[^a-zA-Z0-9\-_.\s]/g, '');
			sanitized = sanitized.replace(/\s+/g, ' ').trim();

			if (sanitized.length > CONSTANTS.MAX_UTM_LENGTH) {
				console.warn(`UTMTrackJS: Valor UTM truncado (máximo: ${CONSTANTS.MAX_UTM_LENGTH} caracteres)`);
				sanitized = sanitized.substring(0, CONSTANTS.MAX_UTM_LENGTH);
			}

			return sanitized.length > 0 ? sanitized : null;
		},

		/**
		 * Valida valor UTM
		 * @param {any} value - Valor a ser validado
		 * @returns {boolean} True se válido
		 */
		isValidUtmValue(value) {
			const sanitized = this.sanitizeUtmValue(value);
			return sanitized !== null && sanitized.length > 0;
		},

		/**
		 * Valida metadados de timestamp e origem
		 * @param {Object} utms - Objeto com dados UTM e metadados
		 * @returns {boolean} True se válidos
		 */
		validateMetadata(utms) {
			const now = Date.now();
			const tenYearsAgo = now - (10 * 365 * 24 * 60 * 60 * 1000);

			// Valida timestamp
			if (typeof utms._timestamp !== 'number' || isNaN(utms._timestamp) || 
					utms._timestamp <= 0 || utms._timestamp < tenYearsAgo || 
					utms._timestamp > now) {
				console.warn('UTMTrackJS: Timestamp inválido detectado.');
				return false;
			}

			// Validação de origem (anti-CSRF)
			if (utms._origin && typeof utms._origin === 'string') {
				try {
					const storedOrigin = new URL(utms._origin).origin;
					if (storedOrigin !== window.location.origin) {
						console.warn('UTMTrackJS: Origem dos dados não confere. Possível CSRF detectado.');
						return false;
					}
				} catch (urlError) {
					console.warn('UTMTrackJS: Origem inválida nos dados armazenados.');
					return false;
				}
			}

			// Verifica expiração se habilitada
			if (AppState.config.maxDataAge !== false && (now - utms._timestamp) > AppState.config.maxDataAge) {
				console.warn('UTMTrackJS: Dados no localStorage expirados.');
				return false;
			}

			return true;
		},

		/**
		 * Verifica se dados do localStorage são seguros
		 * @param {Object} utms - Dados do localStorage
		 * @returns {boolean} True se seguros
		 */
		validateStoredData(utms) {
			if (typeof utms !== 'object' || utms === null || utms.constructor !== Object) {
				console.warn('UTMTrackJS: Estrutura de dados inválida detectada.');
				return false;
			}

			// Proteção contra prototype pollution
			if (Object.getPrototypeOf(utms) !== Object.prototype) {
				console.warn('UTMTrackJS: Prototype pollution detectado.');
				return false;
			}

			// Verifica propriedades perigosas
			const dangerousProps = [
				'constructor', '__proto__', 'prototype', 'valueOf', 'toString', 
				'__defineGetter__', '__defineSetter__', '__lookupGetter__', '__lookupSetter__',
				'hasOwnProperty', 'isPrototypeOf', 'propertyIsEnumerable'
			];
			
			for (const prop of dangerousProps) {
				if (utms.hasOwnProperty(prop) && !['_timestamp', '_data', '_origin', '_version'].includes(prop)) {
					console.warn(`UTMTrackJS: Propriedade perigosa detectada: ${prop}`);
					return false;
				}
			}

			// Validação adicional contra prototype pollution
			if (Object.prototype.toString.call(utms) !== '[object Object]') {
				console.warn('UTMTrackJS: Objeto suspeito detectado - possível prototype pollution.');
				return false;
			}

			// Verifica limite de chaves
			if (Object.keys(utms).length > CONSTANTS.MAX_KEYS) {
				console.warn(`UTMTrackJS: Muitas chaves no localStorage (${Object.keys(utms).length}, máximo: ${CONSTANTS.MAX_KEYS})`);
				return false;
			}

			const hasMetadata = utms._timestamp && utms._data;
			const dataToValidate = hasMetadata ? utms._data : utms;

			// Valida metadata se presente
			if (hasMetadata && !this.validateMetadata(utms)) {
				return false;
			}

			// Proteção adicional nos dados
			if (hasMetadata && utms._data) {
				if (typeof utms._data !== 'object' || Array.isArray(utms._data) || utms._data === null) {
					console.warn('UTMTrackJS: Estrutura de _data inválida.');
					return false;
				}
				if (Object.getPrototypeOf(utms._data) !== Object.prototype) {
					console.warn('UTMTrackJS: Prototype pollution detectado nos dados.');
					return false;
				}
			}

			// Valida cada chave e valor
			for (const [key, value] of Object.entries(dataToValidate)) {
				if (!this.isValidUtmKey(key) || typeof value !== 'string' || value.length > CONSTANTS.MAX_UTM_LENGTH) {
					console.warn(`UTMTrackJS: Dados inválidos para chave ${key}`);
					return false;
				}

				const sanitized = this.sanitizeUtmValue(value);
				if (!sanitized || sanitized !== value) {
					console.warn(`UTMTrackJS: Valor comprometido encontrado para chave ${key}`);
					return false;
				}
			}

			return true;
		}
	};

	// Módulo de log centralizado
	const Log = {
		info(...args) { if (AppState.config.loggingEnabled) { try { console.log(...args); } catch(_) {} } },
		warn(...args) { if (AppState.config.loggingEnabled) { try { console.warn(...args); } catch(_) {} } },
		error(...args) { try { console.error(...args); } catch(_) {} }
	};

	// Módulo de armazenamento localStorage
	const StorageModule = {
		// Rate limiting para operações de storage
		_lastSaveTime: 0,
		_saveThrottle: 100, // ms mínimo entre salvamentos

		/**
		 * Verifica se pode realizar operação de salvamento (rate limiting)
		 */
		_canSave() {
			const now = Date.now();
			if (now - this._lastSaveTime < this._saveThrottle) {
				return false;
			}
			this._lastSaveTime = now;
			return true;
		},

		/**
		 * Obtém dados do localStorage com validação de segurança
		 * @returns {Object|null} Dados UTM ou null se não existirem/inválidos
		 */
		getStoredData() {
			try {
				const savedData = localStorage.getItem(CONSTANTS.STORAGE_KEY);
				if (!savedData) {
					return null;
				}
				
				// Validação prévia para evitar ataques
				if (typeof savedData !== 'string' || savedData.length > CONSTANTS.MAX_STORAGE_SIZE) {
					console.warn('UTMTrackJS: Dados suspeitos no localStorage.');
					this.cleanup();
					return null;
				}

				// Verificação básica de estrutura JSON
				const firstChar = savedData.trim().charAt(0);
				const lastChar = savedData.trim().charAt(savedData.trim().length - 1);
				if (firstChar !== '{' || lastChar !== '}') {
					console.warn('UTMTrackJS: Estrutura JSON inválida detectada.');
					this.cleanup();
					return null;
				}
				
				// Parse seguro
				let parsed;
				try {
					parsed = JSON.parse(savedData);
				} catch (parseError) {
					console.warn('UTMTrackJS: Erro ao fazer parse dos dados JSON.', parseError);
					this.cleanup();
					return null;
				}
				
				if (!ValidationModule.validateStoredData(parsed)) {
					console.warn('UTMTrackJS: Dados corrompidos ou inseguros no localStorage. Limpando...');
					this.cleanup();
					return null;
				}
				
				// Se tem metadata, retorna apenas os dados
				return parsed._timestamp && parsed._data ? parsed._data : parsed;
			} catch (error) {
				console.error('UTMTrackJS: Erro ao ler do localStorage.', error);
				this.cleanup();
				return null;
			}
		},

		/**
		 * Salva dados no localStorage com metadata de segurança
		 * @param {Object} data - Dados UTM a serem salvos
		 * @returns {boolean} True se salvou com sucesso
		 */
		saveStoredData(data) {
			try {
				// Rate limiting para evitar spam
				if (!this._canSave()) {
					console.warn('UTMTrackJS: Operação de salvamento muito frequente. Ignorando.');
					return false;
				}

				if (!data || typeof data !== 'object' || Object.keys(data).length > CONSTANTS.MAX_KEYS) {
					throw new UTMTrackError('Dados inválidos ou muitos dados para salvamento.', 'INVALID_DATA');
				}

				const dataWithMetadata = {
					_timestamp: Date.now(),
					_data: data,
					_origin: window.location.origin,
					_version: CONSTANTS.VERSION
				};

				const serialized = JSON.stringify(dataWithMetadata);
				
				if (serialized.length > CONSTANTS.MAX_STORAGE_SIZE) {
					throw new UTMTrackError('Dados muito grandes para salvar no localStorage.', 'SIZE_LIMIT');
				}

				localStorage.setItem(CONSTANTS.STORAGE_KEY, serialized);
				return true;
			} catch (error) {
				console.error('UTMTrackJS: Erro ao salvar no localStorage.', error);
				return false;
			}
		},

		/**
		 * Limpa dados corrompidos do localStorage
		 */
		cleanup() {
			try {
				localStorage.removeItem(CONSTANTS.STORAGE_KEY);
			} catch (cleanupError) {
				console.error('UTMTrackJS: Erro ao limpar localStorage corrompido.', cleanupError);
			}
		},

		/**
		 * Verifica uso do localStorage e retorna estatísticas
		 * @returns {Object} Estatísticas de uso do storage
		 */
		getStorageStats() {
			try {
				const data = localStorage.getItem(CONSTANTS.STORAGE_KEY);
				if (!data) {
					return {
						exists: false,
						size: 0,
						sizeInKB: 0,
						percentOfLimit: 0
					};
				}

				const sizeInBytes = new Blob([data]).size;
				const sizeInKB = Math.round(sizeInBytes / 1024 * 100) / 100;
				const percentOfLimit = Math.round((sizeInBytes / CONSTANTS.MAX_STORAGE_SIZE) * 100);

				return {
					exists: true,
					size: sizeInBytes,
					sizeInKB,
					percentOfLimit,
					maxSizeKB: Math.round(CONSTANTS.MAX_STORAGE_SIZE / 1024)
				};
			} catch (error) {
				console.error('UTMTrackJS: Erro ao calcular estatísticas de storage.', error);
				return { error: true };
			}
		}
	};

	// Módulo de utilitários e helpers
	const UtilsModule = {
		/**
		 * Retorna lista ativa de chaves UTM
		 * @returns {Array} Array com as chaves UTM ativas
		 */
		getActiveUtmKeys() {
			return AppState.config.customUtmKeys || DEFAULT_UTM_KEYS;
		},

		/**
		 * Verifica se CSP permite criação de eventos dinâmicos
		 */
		_checkCSPCompliance() {
			try {
				const testEvent = new Event('test');
				return true;
			} catch (error) {
				console.warn('UTMTrackJS: CSP pode estar restringindo criação de eventos.');
				return false;
			}
		},

		/**
		 * Dispara eventos de forma segura (compatível com CSP)
		 * @param {HTMLElement} element - Elemento onde disparar o evento
		 * @param {string} eventType - Tipo do evento
		 * @returns {boolean} True se o evento foi disparado com sucesso
		 */
		dispatchSafeEvent(element, eventType) {
			try {
				// Whitelist de eventos permitidos
				if (!CONSTANTS.ALLOWED_EVENTS.includes(eventType)) {
					console.warn(`UTMTrackJS: Tipo de evento '${eventType}' não é permitido.`);
					return false;
				}

				if (!this._checkCSPCompliance()) {
					console.warn('UTMTrackJS: CSP restritivo detectado. Pulando criação de evento.');
					return false;
				}

				if (typeof Event === 'function') {
					element.dispatchEvent(new Event(eventType, { bubbles: true }));
				} else if (document.createEvent) {
					const event = document.createEvent('HTMLEvents');
					event.initEvent(eventType, true, false);
					element.dispatchEvent(event);
				} else {
					console.warn('UTMTrackJS: Não foi possível disparar evento - API de eventos não disponível.');
					return false;
				}
				return true;
			} catch (eventError) {
				console.warn('UTMTrackJS: Não foi possível disparar evento:', eventError);
				return false;
			}
		},

		/**
		 * Dispara eventos customizados do UTMTrackJS
		 * @param {string} eventType - Tipo do evento customizado
		 * @param {Object} detail - Detalhes do evento
		 * @returns {boolean} True se o evento foi disparado com sucesso
		 */
		dispatchCustomEvent(eventType, detail = {}) {
			try {
				if (!Object.values(CONSTANTS.CUSTOM_EVENTS).includes(eventType)) {
					console.warn(`UTMTrackJS: Tipo de evento customizado '${eventType}' não é reconhecido.`);
					return false;
				}

				// Validação de segurança do detail
				if (detail && typeof detail === 'object') {
					// Remove propriedades perigosas
					const safeDangerousProps = ['constructor', '__proto__', 'prototype'];
					for (const prop of safeDangerousProps) {
						if (detail.hasOwnProperty(prop)) {
							console.warn(`UTMTrackJS: Propriedade perigosa removida do evento: ${prop}`);
							delete detail[prop];
						}
					}
					
					// Limita o tamanho do detail
					if (JSON.stringify(detail).length > 10000) {
						console.warn('UTMTrackJS: Detail do evento muito grande, limitando...');
						detail = { truncated: true, originalSize: 'too_large' };
					}
				}

				const event = new CustomEvent(eventType, {
					detail: {
						timestamp: Date.now(),
						version: CONSTANTS.VERSION,
						...detail
					},
					bubbles: false,
					cancelable: false
				});

				window.dispatchEvent(event);
				return true;
			} catch (error) {
				console.warn('UTMTrackJS: Não foi possível disparar evento customizado:', error);
				return false;
			}
		},

		/**
		 * Throttle function para limitar execução de funções
		 * @param {Function} func - Função a ser limitada
		 * @param {number} delay - Delay em milissegundos
		 * @returns {Function} Função com throttle aplicado
		 */
		throttle(func, delay) {
			let timeoutId;
			let lastExecTime = 0;
			return function (...args) {
				const currentTime = Date.now();
				
				if (currentTime - lastExecTime > delay) {
					func.apply(this, args);
					lastExecTime = currentTime;
				} else {
					clearTimeout(timeoutId);
					timeoutId = setTimeout(() => {
						func.apply(this, args);
						lastExecTime = Date.now();
					}, delay - (currentTime - lastExecTime));
				}
			};
		}
	};

	// Módulo de captura de parâmetros UTM
	const CaptureModule = {
		/**
		 * Captura parâmetros UTM da URL atual e salva no localStorage
		 */
		captureAndSave() {
			try {
				if (typeof URLSearchParams === 'undefined') {
					throw new UTMTrackError('URLSearchParams não está disponível neste navegador.', 'NO_URL_SEARCH_PARAMS');
				}

				const currentUrl = window.location.href;
				if (!currentUrl || currentUrl.length > CONSTANTS.MAX_URL_LENGTH) {
					throw new UTMTrackError('URL inválida ou muito longa.', 'INVALID_URL');
				}

				const urlParams = new URLSearchParams(window.location.search);
				const utmsFound = {};
				let hasUtms = false;
				let processedParams = 0;

				UtilsModule.getActiveUtmKeys().forEach(key => {
					if (processedParams >= CONSTANTS.MAX_PARAMS) {
						console.warn('UTMTrackJS: Muitos parâmetros na URL. Limitando processamento.');
						return;
					}

					if (urlParams.has(key)) {
						const value = urlParams.get(key);
						
						if (value && typeof value === 'string' && value.length <= 1000) {
							const sanitizedValue = ValidationModule.sanitizeUtmValue(value);
							if (sanitizedValue) {
								utmsFound[key] = sanitizedValue;
								hasUtms = true;
								processedParams++;
							} else {
								console.warn(`UTMTrackJS: Valor UTM inválido ignorado para ${key}.`);
							}
						} else {
							console.warn(`UTMTrackJS: Valor UTM muito longo ignorado para ${key}.`);
						}
					}
				});

				if (hasUtms) {
					const existingUtms = StorageModule.getStoredData() || {};
					const updatedUtms = AppState.config.updateWithLatest ? 
						{ ...existingUtms, ...utmsFound } : 
						(Object.keys(existingUtms).length === 0 ? utmsFound : existingUtms);

					if (AppState.config.updateWithLatest || Object.keys(existingUtms).length === 0) {
						StorageModule.saveStoredData(updatedUtms);
						
						// Dispara evento de captura
						UtilsModule.dispatchCustomEvent(CONSTANTS.CUSTOM_EVENTS.UTM_CAPTURED, {
							capturedUtms: utmsFound,
							allUtms: updatedUtms,
							url: currentUrl
						});
					}
				}
			} catch (error) {
				console.error('UTMTrackJS: Erro ao capturar ou salvar UTMs.', error);
			}
		}
	};

	// Módulo de preenchimento de elementos
	const PopulateModule = {
		/**
		 * Preenche elementos HTML com atributo [data-utmtrackjs] com valores UTM
		 */
		populateFromAttributes() {
			try {
				const elements = document.querySelectorAll('[data-utmtrackjs]');
				
				elements.forEach(el => {
					try {
						const utmKey = el.getAttribute('data-utmtrackjs');
						if (!ValidationModule.isValidUtmKey(utmKey)) {
							console.warn('UTMTrackJS: Atributo data-utmtrackjs inválido encontrado:', el);
							return;
						}

						const utmValue = PublicAPI.getUtm(utmKey);
						if (!utmValue) return;

						const safeValue = ValidationModule.sanitizeUtmValue(utmValue);
						if (!safeValue) {
							console.warn('UTMTrackJS: Valor UTM não é seguro para uso:', utmValue);
							return;
						}
						
						this.fillElement(el, safeValue);
					} catch (elementError) {
						console.warn('UTMTrackJS: Erro ao processar elemento:', el, elementError);
					}
				});
			} catch (error) {
				console.error('UTMTrackJS: Erro ao preencher elementos com atributos UTM.', error);
			}
		},

		/**
		 * Preenche um elemento específico com um valor
		 * @param {HTMLElement} element - Elemento a ser preenchido
		 * @param {string} value - Valor a ser inserido
		 */
		fillElement(element, value) {
			const tagName = element.tagName.toLowerCase();
			
			if (CONSTANTS.FORM_ELEMENTS.includes(tagName)) {
				if (!element.disabled && !element.readOnly) {
					const inputType = element.type ? element.type.toLowerCase() : 'text';
					
					if (CONSTANTS.ALLOWED_INPUT_TYPES.includes(inputType)) {
						element.value = value;
						UtilsModule.dispatchSafeEvent(element, 'input');
					} else {
						console.warn(`UTMTrackJS: Tipo de input '${inputType}' não é permitido para preenchimento automático`);
					}
				}
			} else {
				element.textContent = value;
			}
		}
	};

	// Módulo de monitoramento de URL
	const URLMonitorModule = {
		/**
		 * Monitora mudanças na URL para atualizar UTMs automaticamente
		 */
		setup() {
			if (AppState.runtime.urlChangeListenerAdded) {
				return;
			}

			try {
				Log.info('UTMTrackJS: Configurando monitoramento de mudanças de URL...');
				AppState.runtime.lastUrl = window.location.href;

				// Monitora mudanças via History API
				this.setupHistoryAPIMonitoring();

				// Monitora mudanças via popstate e hashchange
				this.addSafeEventListener('popstate', this.handleUrlChange);
				this.addSafeEventListener('hashchange', this.handleUrlChange);

				AppState.runtime.urlChangeListenerAdded = true;
				Log.info('UTMTrackJS: Monitoramento de URL configurado com sucesso!');
			} catch (error) {
				console.error('UTMTrackJS: Erro ao configurar monitoramento de URL.', error);
			}
		},

		/**
		 * Adiciona event listener de forma segura evitando duplicatas
		 */
		addSafeEventListener(eventType, handler) {
			const listenerKey = `${eventType}_${handler.name}`;
			if (!AppState.runtime.eventListeners.has(listenerKey)) {
				window.addEventListener(eventType, handler);
				AppState.runtime.eventListeners.add(listenerKey);
			}
		},

		/**
		 * Remove event listener de forma segura
		 */
		removeSafeEventListener(eventType, handler) {
			const listenerKey = `${eventType}_${handler.name}`;
			if (AppState.runtime.eventListeners.has(listenerKey)) {
				window.removeEventListener(eventType, handler);
				AppState.runtime.eventListeners.delete(listenerKey);
			}
		},

		/**
		 * Configura monitoramento da History API usando interceptação segura
		 */
		setupHistoryAPIMonitoring() {
			if (AppState.runtime.originalHistory) { return; }
			
			// Validação de segurança antes de modificar a History API
			if (typeof history.pushState !== 'function' || typeof history.replaceState !== 'function') {
				Log.warn('UTMTrackJS: History API não está disponível ou foi comprometida.');
				return;
			}
			
			AppState.runtime.originalHistory = {
				pushState: history.pushState.bind(history),
				replaceState: history.replaceState.bind(history)
			};
			
			try {
				let historyChangeTimeout;
				
				const safeHandleHistoryChange = function() {
					clearTimeout(historyChangeTimeout);
					historyChangeTimeout = setTimeout(() => {
						try {
							URLMonitorModule.handleUrlChange();
						} catch (error) {
							console.error('UTMTrackJS: Erro ao processar mudança de histórico:', error);
						}
					}, 10); // Debounce de 10ms
				};
				
				// Wrapper seguro que preserva a funcionalidade original
				const createHistoryWrapper = (originalMethod, methodName) => {
					return function(...args) {
						try {
							const result = originalMethod.apply(this, args);
							safeHandleHistoryChange();
							return result;
						} catch (error) {
							console.error(`UTMTrackJS: Erro em ${methodName}:`, error);
							throw error;
						}
					};
				};
				
				history.pushState = createHistoryWrapper(AppState.runtime.originalHistory.pushState, 'pushState');
				history.replaceState = createHistoryWrapper(AppState.runtime.originalHistory.replaceState, 'replaceState');
			} catch (e) {
				Log.warn('UTMTrackJS: Falha ao envolver History API, restaurando originais.', e);
				AppState.runtime.originalHistory = null;
			}
		},

		disable() {
			try {
				// Restauração segura da History API
				if (AppState.runtime.originalHistory) {
					if (typeof AppState.runtime.originalHistory.pushState === 'function') {
						history.pushState = AppState.runtime.originalHistory.pushState;
					}
					if (typeof AppState.runtime.originalHistory.replaceState === 'function') {
						history.replaceState = AppState.runtime.originalHistory.replaceState;
					}
					AppState.runtime.originalHistory = null;
				}
				
				// Remove todos os event listeners registrados
				this.removeSafeEventListener('popstate', this.handleUrlChange);
				this.removeSafeEventListener('hashchange', this.handleUrlChange);
				
				AppState.runtime.urlChangeListenerAdded = false;
				AppState.runtime.urlListenersBound = false;
				Log.info('UTMTrackJS: Monitoramento de URL desativado.');
				return true;
			} catch (e) {
				console.error('UTMTrackJS: Erro ao desativar monitoramento de URL.', e);
				return false;
			}
		},

		/**
		 * Manipula mudanças de URL com throttling
		 */
		handleUrlChange: UtilsModule.throttle(() => {
			try {
				const currentUrl = window.location.href;
				Log.info('UTMTrackJS: Detectada mudança de URL de', AppState.runtime.lastUrl, 'para', currentUrl);
				
				if (currentUrl !== AppState.runtime.lastUrl) {
					AppState.runtime.lastUrl = currentUrl;
					
					// Só recaptura se updateWithLatest estiver habilitado
					if (AppState.config.updateWithLatest) {
						Log.info('UTMTrackJS: Recapturando UTMs devido à mudança de URL...');
						CaptureModule.captureAndSave();
						PopulateModule.populateFromAttributes();
						Log.info('UTMTrackJS: UTMs recapturados e elementos atualizados!');
					} else {
						Log.info('UTMTrackJS: updateWithLatest está desabilitado, ignorando mudança de URL.');
					}
				}
			} catch (error) {
				console.error('UTMTrackJS: Erro ao processar mudança de URL.', error);
			}
		}, CONSTANTS.THROTTLE_DELAY)
	};

	// API pública da biblioteca
	const PublicAPI = {
		/**
		 * Recupera valor de uma chave UTM específica do localStorage
		 * @param {string} key - Chave UTM a ser recuperada
		 * @returns {string|null} Valor da UTM ou null se não existir
		 */
		getUtm(key) {
			if (!ValidationModule.isValidUtmKey(key)) {
				console.warn('UTMTrackJS: Chave UTM inválida fornecida para getUtm.');
				return null;
			}
			const utms = StorageModule.getStoredData();
			return utms ? (utms[key] || null) : null;
		},

		/**
		 * Recupera todas as UTMs salvas no localStorage
		 * @returns {Object|null} Objeto com todas as UTMs ou null se não existirem
		 */
		getAllUtms() {
			const utms = StorageModule.getStoredData();
			return utms ? { ...utms } : null;
		},

		/**
		 * Remove uma ou todas as UTMs do localStorage
		 * @param {string} [key] - Chave UTM a ser removida. Se undefined, remove todas
		 * @returns {boolean} True se removeu com sucesso
		 */
		removeUtm(key) {
			try {
				if (key === undefined) {
					localStorage.removeItem(CONSTANTS.STORAGE_KEY);
					PopulateModule.populateFromAttributes();
					return true;
				}

				if (!ValidationModule.isValidUtmKey(key)) {
					console.warn('UTMTrackJS: Chave UTM inválida fornecida para removeUtm:', key);
					return false;
				}

				const utms = StorageModule.getStoredData();
				if (!utms || !utms.hasOwnProperty(key)) return true;

				const removedValue = utms[key];
				delete utms[key];

				if (Object.keys(utms).length === 0) {
					localStorage.removeItem(CONSTANTS.STORAGE_KEY);
				} else {
					StorageModule.saveStoredData(utms);
				}

				PopulateModule.populateFromAttributes();
				
				// Dispara evento de remoção
				UtilsModule.dispatchCustomEvent(CONSTANTS.CUSTOM_EVENTS.UTM_REMOVED, {
					removedKey: key,
					removedValue: removedValue,
					remainingUtms: utms
				});
				
				return true;
			} catch (error) {
				console.error('UTMTrackJS: Erro ao remover UTM.', error);
				return false;
			}
		},

		/**
		 * Define um ou múltiplos parâmetros UTM no localStorage
		 * @param {string|Object} keyOrObject - Chave UTM ou objeto com chaves/valores
		 * @param {string} [value] - Valor da UTM (se keyOrObject for string)
		 * @returns {boolean} True se definiu com sucesso
		 */
		setUtm(keyOrObject, value) {
			try {
				const existingUtms = StorageModule.getStoredData() || {};
				let utmsToSet = {};

				if (typeof keyOrObject === 'string') {
					if (!ValidationModule.isValidUtmKey(keyOrObject) || !ValidationModule.isValidUtmValue(value)) {
						throw new UTMTrackError('Chave ou valor UTM inválido.', 'INVALID_INPUT');
					}

					if (typeof value === 'object') {
						throw new UTMTrackError('Valor não pode ser objeto ou array.', 'INVALID_VALUE_TYPE');
					}
					
					const sanitizedValue = ValidationModule.sanitizeUtmValue(value);
					if (!sanitizedValue) {
						throw new UTMTrackError('Valor inválido após sanitização.', 'INVALID_VALUE');
					}
					
					utmsToSet[keyOrObject] = sanitizedValue;
				} else if (typeof keyOrObject === 'object' && keyOrObject !== null && !Array.isArray(keyOrObject)) {
					for (const [key, val] of Object.entries(keyOrObject)) {
						if (!ValidationModule.isValidUtmKey(key)) {
							console.warn(`UTMTrackJS: Ignorando chave inválida ${key}`);
							continue;
						}
						if (typeof val === 'object') {
							console.warn(`UTMTrackJS: Valor complexo ignorado para chave ${key}`);
							continue;
						}
						if (!ValidationModule.isValidUtmValue(val)) {
							console.warn(`UTMTrackJS: Valor inválido para chave ${key}`);
							continue;
						}
						
						const sanitizedValue = ValidationModule.sanitizeUtmValue(val);
						if (sanitizedValue) {
							utmsToSet[key] = sanitizedValue;
						}
					}
					
					if (Object.keys(utmsToSet).length === 0) {
						throw new UTMTrackError('Nenhuma UTM válida encontrada no objeto fornecido.', 'NO_VALID_UTMS');
					}
				} else {
					throw new UTMTrackError('Primeiro parâmetro deve ser uma string ou objeto.', 'INVALID_PARAMETER_TYPE');
				}

				const updatedUtms = { ...existingUtms, ...utmsToSet };
				if (Object.keys(updatedUtms).length > CONSTANTS.MAX_KEYS) {
					throw new UTMTrackError('Quantidade total de chaves excede o limite.', 'KEY_LIMIT');
				}
				
				StorageModule.saveStoredData(updatedUtms);
				PopulateModule.populateFromAttributes();
				
				// Dispara evento de atualização
				UtilsModule.dispatchCustomEvent(CONSTANTS.CUSTOM_EVENTS.UTM_UPDATED, {
					updatedKeys: Object.keys(utmsToSet),
					updatedValues: utmsToSet,
					allUtms: updatedUtms
				});
				
				return true;
			} catch (error) {
				console.error('UTMTrackJS: Erro ao definir UTMs.', error);
				return false;
			}
		},

		/**
		 * Configura o comportamento da biblioteca
		 * @param {Object} options - Opções de configuração
		 * @returns {boolean} True se configurou com sucesso
		 */
		configure(options) {
			try {
				if (typeof options !== 'object' || options === null || Array.isArray(options) ||
						options.constructor !== Object || Object.keys(options).length > 10) {
					throw new UTMTrackError('Opções de configuração inválidas.', 'INVALID_CONFIG');
				}

				// Proteção contra prototype pollution
				if (options.__proto__ !== Object.prototype) {
					throw new UTMTrackError('Prototype pollution detectado nas opções.', 'PROTOTYPE_POLLUTION');
				}

				// Lista de propriedades permitidas
				const allowedConfigKeys = ['updateWithLatest', 'maxDataAge', 'customUtmKeys', 'loggingEnabled'];
				const providedKeys = Object.keys(options);
				
				// Verifica se todas as chaves fornecidas são permitidas
				for (const key of providedKeys) {
					if (!allowedConfigKeys.includes(key)) {
						console.warn(`UTMTrackJS: Chave de configuração não permitida ignorada: ${key}`);
						delete options[key];
					}
				}

				if (options.hasOwnProperty('updateWithLatest') && typeof options.updateWithLatest === 'boolean') {
					const wasEnabled = AppState.config.updateWithLatest;
					AppState.config.updateWithLatest = options.updateWithLatest;
					
					// Configura ou remove monitoramento de URL
					if (AppState.config.updateWithLatest && !wasEnabled) {
						URLMonitorModule.setup();
					}
					
					// Re-popula elementos se necessário
					if (AppState.runtime.isInitialized) {
						PopulateModule.populateFromAttributes();
					}
				}

				if (options.hasOwnProperty('maxDataAge')) {
					if (options.maxDataAge === false) {
						AppState.config.maxDataAge = false;
						console.info('UTMTrackJS: Expiração de dados desabilitada.');
					} else if (typeof options.maxDataAge === 'number' && options.maxDataAge > 0 && 
										 options.maxDataAge <= (365 * 24 * 60 * 60 * 1000)) {
						AppState.config.maxDataAge = options.maxDataAge;
						console.info(`UTMTrackJS: Tempo de expiração definido para ${Math.round(options.maxDataAge / (1000 * 60 * 60 * 24))} dias.`);
					} else {
						console.warn('UTMTrackJS: maxDataAge deve ser um número positivo (em ms) menor que 1 ano ou false.');
					}
				}

				if (options.hasOwnProperty('customUtmKeys')) {
					if (Array.isArray(options.customUtmKeys)) {
						if (options.customUtmKeys.length > 100) {
							console.warn('UTMTrackJS: Muitas chaves personalizadas (máximo: 100).');
							return false;
						}

						const validKeys = options.customUtmKeys.filter(key => {
							if (ValidationModule.isValidUtmKey(key)) {
								return true;
							} else {
								console.warn(`UTMTrackJS: Chave UTM personalizada inválida ignorada: ${key}`);
								return false;
							}
						});
						// Remove duplicadas
						const deduped = [...new Set(validKeys)];
						if (deduped.length + DEFAULT_UTM_KEYS.length > CONSTANTS.MAX_KEYS) {
							console.warn('UTMTrackJS: Soma de chaves padrão + personalizadas excede limite. Reduza a lista.');
							return false;
						}
						AppState.config.customUtmKeys = deduped.length > 0 ? deduped : null;
					} else if (options.customUtmKeys === null) {
						AppState.config.customUtmKeys = null;
					} else {
						console.warn('UTMTrackJS: customUtmKeys deve ser um array de strings ou null.');
					}
				}

				if (options.hasOwnProperty('loggingEnabled')) {
					AppState.config.loggingEnabled = !!options.loggingEnabled;
				}

				// Dispara evento de configuração alterada
				UtilsModule.dispatchCustomEvent(CONSTANTS.CUSTOM_EVENTS.CONFIG_CHANGED, {
					changedOptions: Object.keys(options),
					newConfig: {
						updateWithLatest: AppState.config.updateWithLatest,
						maxDataAge: AppState.config.maxDataAge,
						customUtmKeys: AppState.config.customUtmKeys,
						loggingEnabled: AppState.config.loggingEnabled
					}
				});

				return true;
			} catch (error) {
				console.error('UTMTrackJS: Erro ao configurar biblioteca.', error);
				return false;
			}
		},

		/**
		 * Adiciona chaves UTM personalizadas à lista existente
		 * @param {string|Array} keys - Chave(s) UTM a serem adicionadas
		 * @returns {boolean} True se adicionou com sucesso
		 */
		addUtmKeys(keys) {
			try {
				const keysArray = Array.isArray(keys) ? keys : [keys];
				const currentKeys = AppState.config.customUtmKeys ? [...AppState.config.customUtmKeys] : [...DEFAULT_UTM_KEYS];
				let addedCount = 0;

				keysArray.forEach(key => {
					if (ValidationModule.isValidUtmKey(key) && !currentKeys.includes(key)) {
						currentKeys.push(key);
						addedCount++;
					} else if (!ValidationModule.isValidUtmKey(key)) {
						console.warn(`UTMTrackJS: Chave UTM inválida ignorada: ${key}`);
					}
				});

				if (currentKeys.length > CONSTANTS.MAX_KEYS) {
					console.warn('UTMTrackJS: Limite de chaves excedido. Operação revertida.');
					return false;
				}

				if (addedCount > 0) {
					AppState.config.customUtmKeys = currentKeys;
					return true;
				}
				return false;
			} catch (error) {
				console.error('UTMTrackJS: Erro ao adicionar chaves UTM.', error);
				return false;
			}
		},

		/**
		 * Remove chaves UTM personalizadas da lista ativa
		 * @param {string|Array} keys - Chave(s) UTM a serem removidas
		 * @returns {boolean} True se removeu com sucesso
		 */
		removeUtmKeys(keys) {
			try {
				const keysArray = Array.isArray(keys) ? keys : [keys];
				const currentKeys = UtilsModule.getActiveUtmKeys();
				const newKeys = currentKeys.filter(key => !keysArray.includes(key));

				if (newKeys.length !== currentKeys.length) {
					AppState.config.customUtmKeys = newKeys.length > 0 ? newKeys : null;
					return true;
				}
				return false;
			} catch (error) {
				console.error('UTMTrackJS: Erro ao remover chaves UTM.', error);
				return false;
			}
		},

		/**
		 * Obtém a configuração atual da biblioteca
		 * @returns {Object} Configuração atual
		 */
		getConfig() {
			return {
				updateWithLatest: AppState.config.updateWithLatest,
				dataExpirationEnabled: AppState.config.maxDataAge !== false,
				version: CONSTANTS.VERSION,
				isInitialized: AppState.runtime.isInitialized,
				loggingEnabled: AppState.config.loggingEnabled
			};
		},

		/**
		 * Limpa dados expirados do localStorage
		 * @returns {boolean} True se limpou com sucesso
		 */
		cleanExpiredData() {
			try {
				if (AppState.config.maxDataAge === false) return true;

				const savedData = localStorage.getItem(CONSTANTS.STORAGE_KEY);
				if (!savedData) return true;

				const parsed = JSON.parse(savedData);
				
				if (parsed._timestamp && typeof parsed._timestamp === 'number') {
					const now = Date.now();
					const dataAge = now - parsed._timestamp;
					
					if (parsed._timestamp > now || dataAge > AppState.config.maxDataAge) {
						localStorage.removeItem(CONSTANTS.STORAGE_KEY);
						console.info('UTMTrackJS: Dados expirados ou inválidos foram removidos.');
						return true;
					}
				}
				
				return true;
			} catch (error) {
				console.error('UTMTrackJS: Erro ao limpar dados expirados.', error);
				StorageModule.cleanup();
				return false;
			}
		},

		/**
		 * Força a recaptura dos parâmetros UTM da URL atual
		 * @returns {boolean} True se recapturou com sucesso
		 */
		recapture() {
			try {
				CaptureModule.captureAndSave();
				PopulateModule.populateFromAttributes();
				return true;
			} catch (error) {
				console.error('UTMTrackJS: Erro ao recapturar UTMs.', error);
				return false;
			}
		},

		/**
		 * Retorna informações detalhadas para debugging
		 * @returns {Object} Informações de debug da biblioteca
		 */
		getDebugInfo() {
			try {
				const storageStats = StorageModule.getStorageStats();
				const allUtms = this.getAllUtms();
				const config = this.getConfig();
				
				return {
					version: CONSTANTS.VERSION,
					initialized: AppState.runtime.isInitialized,
					config: config,
					storage: storageStats,
					utms: {
						count: allUtms ? Object.keys(allUtms).length : 0,
						keys: allUtms ? Object.keys(allUtms) : [],
						data: allUtms
					},
					runtime: {
						lastUrl: AppState.runtime.lastUrl,
						urlMonitoringActive: AppState.runtime.urlChangeListenerAdded,
						domListenerAdded: AppState.runtime.domContentLoadedListenerAdded
					},
					limits: {
						maxKeys: CONSTANTS.MAX_KEYS,
						maxUtmLength: CONSTANTS.MAX_UTM_LENGTH,
						maxStorageSize: CONSTANTS.MAX_STORAGE_SIZE
					},
					supportedKeys: UtilsModule.getActiveUtmKeys()
				};
			} catch (error) {
				console.error('UTMTrackJS: Erro ao gerar informações de debug.', error);
				return { error: error.message };
			}
		},

		/**
		 * Desativa monitoramento de URL e restaura History API
		 */
		disableUrlMonitoring() {
			return URLMonitorModule.disable();
		},

		/**
		 * Purga todos dados e restaura estado inicial mínimo
		 */
		purge() {
			try {
				URLMonitorModule.disable();
				localStorage.removeItem(CONSTANTS.STORAGE_KEY);
				AppState.runtime.isInitialized = false;
				AppState.runtime.lastUrl = '';
				PopulateModule.populateFromAttributes();
				Log.info('UTMTrackJS: Purge concluído.');
				return true;
			} catch (e) {
				console.error('UTMTrackJS: Erro ao realizar purge.', e);
				return false;
			}
		}
	};

	// Módulo de inicialização
	const InitializerModule = {
		/**
		 * Função de inicialização da biblioteca
		 */
		initialize() {
			if (AppState.runtime.isInitialized) {
				console.warn('UTMTrackJS: Biblioteca já foi inicializada.');
				return;
			}

			try {
				// Limpa dados expirados se habilitado
				if (AppState.config.maxDataAge !== false) {
					PublicAPI.cleanExpiredData();
				}
				
				// Captura parâmetros UTM da URL atual se necessário
				const existingData = StorageModule.getStoredData();
				if (AppState.config.updateWithLatest || !existingData || Object.keys(existingData).length === 0) {
					CaptureModule.captureAndSave();
				}

				// Configura monitoramento de URL se updateWithLatest estiver habilitado
				if (AppState.config.updateWithLatest) {
					URLMonitorModule.setup();
				}

				// Configura preenchimento automático dos elementos
				this.setupAutoPopulation();

				AppState.runtime.isInitialized = true;
				Log.info('UTMTrackJS: Biblioteca inicializada com sucesso!');
			} catch (error) {
				console.error('UTMTrackJS: Erro durante a inicialização.', error);
			}
		},

		/**
		 * Configura o preenchimento automático dos elementos DOM
		 */
		setupAutoPopulation() {
			if (document.readyState === 'loading') {
				if (!AppState.runtime.domContentLoadedListenerAdded) {
					const domLoadedHandler = () => {
						PopulateModule.populateFromAttributes();
						document.removeEventListener('DOMContentLoaded', domLoadedHandler);
					};
					document.addEventListener('DOMContentLoaded', domLoadedHandler);
					AppState.runtime.domContentLoadedListenerAdded = true;
				}
			} else {
				// DOM já carregado, preenche imediatamente
				PopulateModule.populateFromAttributes();
			}
		}
	};

	// Inicializa a biblioteca automaticamente
	InitializerModule.initialize();

	// Exportação da biblioteca para o window
	window.UTMTrackJS = Object.freeze({
		// Métodos principais de UTM
		getUtm: PublicAPI.getUtm,
		setUtm: PublicAPI.setUtm,
		getAllUtms: PublicAPI.getAllUtms,
		removeUtm: PublicAPI.removeUtm,
		
		// Métodos de configuração
		configure: PublicAPI.configure,
		addUtmKeys: PublicAPI.addUtmKeys,
		removeUtmKeys: PublicAPI.removeUtmKeys,
		getConfig: PublicAPI.getConfig,
		recapture: PublicAPI.recapture,
		disableUrlMonitoring: PublicAPI.disableUrlMonitoring,
		purge: PublicAPI.purge,
		
		// Métodos utilitários
		refresh: PopulateModule.populateFromAttributes,
		cleanExpiredData: PublicAPI.cleanExpiredData,
		getDebugInfo: PublicAPI.getDebugInfo,
		getStorageStats: StorageModule.getStorageStats,
		
		// Informações da biblioteca (somente leitura)
		get version() { return CONSTANTS.VERSION; },
		get storageKey() { return CONSTANTS.STORAGE_KEY; },
		get supportedKeys() { return [...DEFAULT_UTM_KEYS]; },
		get customEvents() { return { ...CONSTANTS.CUSTOM_EVENTS }; }
	});

})(window);