@metodokorexmk/tracking 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,869 @@
+/**
+ * Tipos e interfaces compartidas para @metodokorexmk/tracking
+ */
+/**
+ * Configuración principal del tracking.
+ * Se pasa a `initGA()` para inicializar el sistema.
+ */
+interface TrackingConfig {
+    /** ID de Google Analytics 4 (ej: 'G-XXXXXXX') */
+    trackingId?: string;
+    /**
+     * Función personalizada para resolver el GA Tracking ID dinámicamente.
+     * Recibe la URL actual y debe devolver el ID correspondiente.
+     * Si se proporciona, tiene prioridad sobre `trackingId`.
+     *
+     * @example
+     * ```ts
+     * resolveTrackingId: (url) => {
+     *   if (url.startsWith('/kin')) return 'G-KIN-ID'
+     *   return localStorage.getItem('user_GA_id') || 'G-DEFAULT'
+     * }
+     * ```
+     */
+    resolveTrackingId?: (currentPath: string) => string;
+    /** ID de Google Tag Manager (ej: 'GTM-XXXXXXX'). Si se proporciona, se inyecta GTM automáticamente. */
+    gtmId?: string;
+    /** Habilitar anonimización de IP en GA4 */
+    anonymizeIp?: boolean;
+    /** Modo debug: imprime eventos en consola */
+    debug?: boolean;
+}
+/**
+ * Configuración del LandingTracker (orquestador de sesión).
+ */
+interface LandingTrackerConfig {
+    /** Ruta de la landing page (ej: '/kin', '/racha') */
+    pagePath: string;
+    /** Nombre legible de la landing (ej: 'Kin Landing Page') */
+    pageName: string;
+    /** ID de Google Tag Manager (opcional) */
+    gtmId?: string;
+    /** Habilitar tracking de scroll (milestones 25/50/75/100%). Default: true */
+    enableScrollTracking?: boolean;
+    /** Habilitar tracking automático de clicks en CTAs. Default: true */
+    enableCTATracking?: boolean;
+    /** Habilitar tracking de tiempo en página. Default: true */
+    enableTimeTracking?: boolean;
+    /** Habilitar tracking de tiempo por sección (IntersectionObserver). Default: true */
+    enableSectionTracking?: boolean;
+    /** Habilitar auto-tracking de formularios. Default: true */
+    enableFormTracking?: boolean;
+    /** Habilitar heatmap de clicks (coordenadas X/Y). Default: false */
+    enableHeatmap?: boolean;
+    /** Sufijo personalizado para eventos (ej: '_kin' para 'cta_click_kin'). Default: '' */
+    eventSuffix?: string;
+}
+/**
+ * Parámetros UTM capturados de la URL.
+ */
+interface UTMParams {
+    utm_source?: string;
+    utm_medium?: string;
+    utm_campaign?: string;
+    utm_term?: string;
+    utm_content?: string;
+}
+/**
+ * Datos de identificación del visitante capturados.
+ */
+interface VisitorData {
+    userId?: string;
+    userName?: string;
+    utmParams?: UTMParams;
+    entryTime: number;
+    entryUrl: string;
+}
+/**
+ * Estadísticas de reproducción de un video.
+ * Compartido entre todos los adaptadores (Wistia, Voomly, HTML5).
+ */
+interface VideoStats {
+    /** Tiempo total reproducido en segundos */
+    timeWatched: number;
+    /** Si el video fue completado (≥90-95%) */
+    completed: boolean;
+    /** Timestamp de la última actualización */
+    lastUpdate: number;
+}
+/**
+ * Estado interno detallado de tracking de un video.
+ * Usado internamente por VideoTracker.
+ */
+interface VideoTrackingState {
+    videoId: string;
+    startTime: number;
+    totalWatchTime: number;
+    playCount: number;
+    pauseCount: number;
+    seekCount: number;
+    completionPercentage: number;
+    lastPlayTimestamp: number;
+    isPlaying: boolean;
+    currentTime: number;
+    duration: number;
+    pauseTimes: number[];
+    seekEvents: Array<{
+        from: number;
+        to: number;
+    }>;
+    progressMilestones: Set<number>;
+    playbackSpeed: number;
+}
+/**
+ * Opciones para los hooks de video en React.
+ */
+interface UseVideoTrackingOptions {
+    /** ID único del video */
+    videoId: string;
+    /** Referencia al elemento <video> HTML (solo para HTML5) */
+    videoElement?: HTMLVideoElement | null;
+    /** Callback cuando el video se completa */
+    onComplete?: () => void;
+    /** Callback en milestones de progreso (25, 50, 75) */
+    onProgress?: (percentage: number) => void;
+}
+/**
+ * Callback para actualizaciones de video.
+ */
+type VideoUpdateCallback = (stats: VideoStats) => void;
+/**
+ * Objeto retornado por los adaptadores de video (Wistia, Voomly).
+ */
+interface VideoTrackerHandle {
+    /** Obtener estadísticas actuales */
+    getStats: () => VideoStats;
+    /** Registrar callback de actualización. Retorna función para desregistrar. */
+    onUpdate: (cb: VideoUpdateCallback) => () => void;
+    /** Detener tracking y limpiar listeners */
+    stop: () => void;
+}
+/**
+ * Payload genérico de un evento de tracking.
+ */
+interface TrackingEventData {
+    [key: string]: unknown;
+}
+/**
+ * Datos de un click capturado para heatmap.
+ */
+interface ClickData {
+    x: number;
+    y: number;
+    element: string;
+    section: string;
+    timestamp: number;
+    viewportWidth: number;
+    viewportHeight: number;
+}
+/**
+ * Resumen de sesión al salir de la página.
+ */
+interface SessionSummary {
+    duration: number;
+    scrollDepth: number;
+    clicks: number;
+    sectionsViewed: string[];
+    videoWatchTime: number;
+    formInteractions: number;
+}
+/**
+ * Configuración del cliente HTTP para persistencia.
+ * Se pasa a `initTrackingAPI()`.
+ */
+interface TrackingAPIConfig {
+    /** URL base del API (ej: 'https://api.korex.com/api/v1') */
+    baseUrl: string;
+    /** Función que retorna el token de autenticación (ej: de localStorage) */
+    getAuthToken?: () => string | null;
+    /** Headers adicionales para cada petición */
+    getCustomHeaders?: () => Record<string, string>;
+}
+/**
+ * Modelo de tracking lead del backend.
+ */
+interface TrackingLead {
+    id: number;
+    userName: string;
+    userEmail: string;
+    entryDate: string;
+    accessUrl: string;
+    videoTimeWatched: number;
+    videoCompleted: boolean;
+    leadId: number | null;
+    leadName: string;
+    leadEmail: string;
+    leadPhone: string;
+    leadStatus: string;
+    leadOrigin: string | null;
+    leadMessage: string | null;
+    leadRoledesired: string | null;
+    referringUserId: number | null;
+    status: boolean;
+    whatsappSent: boolean;
+    nameForm: string | null;
+    msgForm: string | null;
+    fieldData?: string;
+    leadPlatform?: string | null;
+    leadCampaign?: string | null;
+    createdAt: string;
+    dwellTime?: number;
+}
+/**
+ * Datos procesados de lead con tracking (respuesta de GET /leads/{id}/with-tracking).
+ */
+interface LeadTrackingData {
+    videoVisto: boolean;
+    tiempoReproducido: string;
+    envioWhatsapp: boolean;
+    accessUrl?: string;
+    nameForm?: string;
+    msgForm?: string;
+    platform?: string;
+    aliasName?: string;
+    trackingId?: number;
+    videoTimeWatched?: number;
+    dwellTime?: number;
+}
+/**
+ * Datos de formulario para enviar con un lead.
+ */
+interface LeadFormData {
+    nombre: string;
+    correo: string;
+    telefono: string;
+    countryLada?: string;
+    [key: string]: unknown;
+}
+/**
+ * Parámetros extraídos de la URL para detección de origen.
+ */
+interface UrlParams {
+    userId: string;
+    idCampana: string;
+    utmContent: string;
+    fbclid: string;
+    nombreNetworker: string;
+    whatsapp: string;
+    pipelineId: string;
+    funnelId?: string;
+    metricId?: string;
+    utmSource?: string;
+    utmMedium?: string;
+    utmCampaign?: string;
+    leadCampaing?: string;
+    isOrganico?: boolean;
+}
+/**
+ * Resultado de la detección de origen de un lead.
+ */
+interface LeadOrigin {
+    type: 'facebook' | 'organic';
+    endpoint: string;
+    params: UrlParams;
+    hasCampaign: boolean;
+}
+/**
+ * Respuesta del API al crear/enviar un tracking lead.
+ */
+interface TrackingLeadResponse {
+    colaboradorAsignado?: {
+        telefono: string;
+        nombre: string;
+        [key: string]: unknown;
+    } | null;
+    trackingId?: number | string | null;
+    leadId?: number | string | null;
+    [key: string]: unknown;
+}
+/**
+ * Respuesta procesada de submitTrackingLead.
+ */
+interface SubmitTrackingLeadResponse {
+    ok: boolean;
+    status: number;
+    data: TrackingLeadResponse | null;
+}
+/**
+ * Opciones adicionales al construir el body de la petición de lead.
+ */
+interface BuildRequestBodyOptions {
+    nameForm?: string;
+    msgForm?: string;
+    status?: string;
+    whatsappSent?: boolean;
+    dwellTime?: number;
+    videoTimeWatched?: number;
+    videoCompleted?: boolean;
+    additionalFields?: Record<string, unknown>;
+}
+/**
+ * Configuración del DwellTimeTracker.
+ */
+interface DwellTimeConfig {
+    /** ID del tracking data en el backend */
+    trackingDataId: number | string;
+    /** Habilitar tracking (default: true) */
+    enabled?: boolean;
+    /** Callback al enviar exitosamente */
+    onSuccess?: () => void;
+    /** Callback en caso de error */
+    onError?: (error: Error) => void;
+}
+declare global {
+    interface Window {
+        gtag?: (...args: unknown[]) => void;
+        dataLayer?: unknown[];
+        _wq?: Array<{
+            id: string;
+            onReady: (video: unknown) => void;
+        }>;
+    }
+}
+
+/**
+ * Core de Google Analytics 4
+ * Inicialización, tracking de eventos y captura de datos del visitante.
+ * Desacoplado de cualquier framework (Next.js, React, etc.)
+ */
+
+/**
+ * Obtiene el GA Tracking ID actual.
+ * Si se configuró un `resolveTrackingId`, lo usa dinámicamente.
+ * Si no, usa el `trackingId` fijo de la config.
+ */
+declare const getGATrackingId: () => string;
+/**
+ * Inicializa Google Analytics con la configuración proporcionada.
+ *
+ * @example
+ * ```ts
+ * // Con ID fijo
+ * initGA({ trackingId: 'G-XXXXXXX' })
+ *
+ * // Con resolución dinámica
+ * initGA({
+ *   resolveTrackingId: (path) => {
+ *     if (path.startsWith('/kin')) return 'G-KIN-ID'
+ *     return localStorage.getItem('user_GA_id') || 'G-DEFAULT'
+ *   }
+ * })
+ * ```
+ */
+declare const initGA: (config?: TrackingConfig) => void;
+/**
+ * Reinicializa GA con un nuevo Tracking ID.
+ * Útil cuando el ID cambia dinámicamente (ej. login del usuario).
+ */
+declare const reinitGA: (newTrackingId: string) => void;
+/**
+ * Verificar si GA está inicializado
+ */
+declare const isGAInitialized: () => boolean;
+/**
+ * Extrae los parámetros UTM de la URL actual.
+ */
+declare const captureUTMParams: () => UTMParams | null;
+/**
+ * Captura el `user_id` desde la URL (?user_id=xxx).
+ * Lo cachea internamente para enviarlo en todos los eventos.
+ */
+declare const captureUserIdFromURL: () => string | null;
+/**
+ * Resuelve el nombre del usuario desde múltiples fuentes.
+ * Prioridad: URL > localStorage > null
+ */
+declare const getUserName: () => string | null;
+/**
+ * Obtiene el user_id cacheado.
+ */
+declare const getUserId: () => string | null;
+/**
+ * Establece manualmente el user_id (ej. después de login).
+ */
+declare const setUserId: (userId: string) => void;
+/**
+ * Establece manualmente el user_name.
+ */
+declare const setUserName: (userName: string) => void;
+/**
+ * Envía un pageview a GA4.
+ * Automáticamente incluye UTM params y user_id si están disponibles.
+ */
+declare const trackPageView: (path: string) => void;
+/**
+ * Envía un evento personalizado a GA4.
+ * Usa envío dual: `window.gtag()` + `ReactGA.event()`.
+ * Siempre incluye `user_id` y `user_name` como parámetros.
+ *
+ * @example
+ * ```ts
+ * trackEvent('CTA', 'click', 'Botón Hero', undefined, { section: 'hero' })
+ * ```
+ */
+declare const trackEvent: (category: string, action: string, label?: string, value?: number, additionalData?: TrackingEventData) => void;
+/**
+ * Resetea el estado interno (útil para tests y re-inicialización).
+ */
+declare const resetAnalytics: () => void;
+
+/**
+ * Google Tag Manager — Carga e inyección vanilla (sin Next.js)
+ * Proporciona pushToDataLayer e injectGTMScript.
+ */
+/**
+ * Inyecta el script de Google Tag Manager en el <head> del documento.
+ * Equivalente al componente <Script> de Next.js, pero framework-agnostic.
+ *
+ * @param gtmId - ID de GTM (ej: 'GTM-5GMQNFMN')
+ *
+ * @example
+ * ```ts
+ * injectGTMScript('GTM-5GMQNFMN')
+ * ```
+ */
+declare const injectGTMScript: (gtmId: string) => void;
+/**
+ * Envía un evento al dataLayer de GTM.
+ *
+ * @param eventName - Nombre del evento
+ * @param data - Datos adicionales del evento
+ *
+ * @example
+ * ```ts
+ * pushToDataLayer('page_view', { page_path: '/kin' })
+ * pushToDataLayer('cta_click', { button_text: 'Únete', section: 'hero' })
+ * ```
+ */
+declare const pushToDataLayer: (eventName: string, data?: Record<string, unknown>) => void;
+
+/**
+ * VideoTracker — Tracking avanzado de video para GA4
+ * Gestiona el estado de reproducción por video y emite eventos a Google Analytics.
+ * Framework-agnostic (no requiere React).
+ */
+
+declare class VideoTracker {
+    private videos;
+    private watchTimeIntervals;
+    /**
+     * Inicializa el tracking para un video.
+     */
+    initVideo(videoId: string): void;
+    /**
+     * Tracking de evento play.
+     */
+    trackPlay(videoId: string, currentTime?: number): void;
+    /**
+     * Tracking de evento pause.
+     */
+    trackPause(videoId: string, currentTime: number, duration?: number): void;
+    /**
+     * Tracking de evento seek (saltar en el timeline).
+     */
+    trackSeek(videoId: string, fromTime: number, toTime: number): void;
+    /**
+     * Tracking de progreso (milestones: 25%, 50%, 75%).
+     */
+    trackProgress(videoId: string, percentage: number, currentTime: number): void;
+    /**
+     * Tracking de completación del video (≥95%).
+     */
+    trackComplete(videoId: string, totalDuration: number): void;
+    /**
+     * Tracking de fin del video (evento ended nativo).
+     */
+    trackEnd(videoId: string): void;
+    /**
+     * Tracking de cambio de velocidad de reproducción.
+     */
+    trackSpeedChange(videoId: string, speed: number): void;
+    /**
+     * Tracking de pantalla completa.
+     */
+    trackFullscreen(videoId: string, isFullscreen: boolean): void;
+    /**
+     * Tracking de no interacción (el usuario está en la página pero no interactúa con el video).
+     */
+    trackNoInteraction(videoId: string, timeOnPage: number): void;
+    /**
+     * Obtiene el estado actual de un video.
+     */
+    getState(videoId: string): VideoTrackingState | undefined;
+    /**
+     * Limpia el tracking de un video específico.
+     */
+    cleanup(videoId: string): void;
+    /**
+     * Limpia todo el tracking.
+     */
+    cleanupAll(): void;
+    private getOrCreateState;
+    private startWatchTimeTracking;
+    private stopWatchTimeTracking;
+}
+/**
+ * Instancia singleton del VideoTracker.
+ * Usar cuando se necesita una sola instancia global.
+ */
+declare const videoTracker: VideoTracker;
+
+/**
+ * Funciones genéricas de tracking de eventos para GA4.
+ * Cada función es una abstracción de `trackEvent()` con categoría y acción predefinidas.
+ */
+
+declare const trackCTAClick: (buttonName: string, section: string, additionalData?: TrackingEventData) => void;
+declare const trackFormStart: (formName: string) => void;
+declare const trackFormFieldComplete: (formName: string, fieldName: string) => void;
+declare const trackFormSubmit: (formName: string, success: boolean, additionalData?: TrackingEventData) => void;
+declare const trackFormValidationError: (formName: string, fieldName: string, errorMessage: string) => void;
+declare const trackConversion: (conversionType: string, value?: number, additionalData?: TrackingEventData) => void;
+declare const trackSocialClick: (platform: string, action: string, additionalData?: TrackingEventData) => void;
+declare const trackFAQExpand: (question: string, index: number) => void;
+declare const trackImageClick: (imageName: string, section: string) => void;
+declare const trackTimeInSection: (sectionName: string, seconds: number) => void;
+declare const trackSectionClick: (section: string) => void;
+declare const trackScrollTo: (section: string) => void;
+declare const trackPricingCardClick: (productName: string, price: number | string, additionalData?: TrackingEventData) => void;
+declare const trackContactClick: (method: string) => void;
+declare const trackShare: (platform: string, content: string) => void;
+declare const trackDownload: (fileName: string, fileType: string) => void;
+
+/**
+ * Adaptador de video Wistia
+ * Detecta automáticamente el SDK de Wistia y se enlaza a sus eventos.
+ * Framework-agnostic.
+ */
+
+/**
+ * Inicia tracking de un video Wistia por su Media ID.
+ * Detecta si el player es Wistia nativo o un <video> HTML5.
+ * Retorna un handle con getStats(), onUpdate() y stop().
+ *
+ * @example
+ * ```ts
+ * const tracker = await trackWistiaByMediaId('abc123')
+ * tracker.onUpdate((stats) => {
+ *   console.log(stats.timeWatched, stats.completed)
+ * })
+ * // Al desmontar:
+ * tracker.stop()
+ * ```
+ */
+declare const trackWistiaByMediaId: (mediaId: string) => Promise<VideoTrackerHandle | null>;
+
+/**
+ * Adaptador de video Voomly
+ * Usa 3 estrategias complementarias para trackear videos embebidos de Voomly.
+ * Framework-agnostic.
+ */
+
+/**
+ * Inicia tracking de un video Voomly por su Embed ID.
+ * Usa 3 estrategias complementarias:
+ * 1. Scan periódico del DOM (cada 2s) buscando <video> dentro del embed
+ * 2. Polling de respaldo (cada 1s) leyendo .currentTime
+ * 3. Eventos globales de window (voomly:video:*)
+ *
+ * @example
+ * ```ts
+ * const tracker = await trackVoomlyByEmbedId('my-voomly-id')
+ * tracker.onUpdate((stats) => console.log(stats))
+ * // IMPORTANTE: llamar stop() al desmontar para evitar memory leaks
+ * tracker.stop()
+ * ```
+ */
+declare const trackVoomlyByEmbedId: (embedId: string) => Promise<VideoTrackerHandle | null>;
+
+/**
+ * Adaptador de video HTML5 nativo
+ * Tracking puro de elementos <video> sin dependencia de React.
+ */
+
+/**
+ * Inicia tracking de un elemento <video> HTML5 nativo.
+ * Escucha eventos estándar del Video API del navegador.
+ *
+ * @example
+ * ```ts
+ * const video = document.querySelector('video')
+ * const tracker = trackHTML5Video('hero-video', video)
+ * tracker.onUpdate((stats) => console.log(stats))
+ * // Al desmontar:
+ * tracker.stop()
+ * ```
+ */
+declare const trackHTML5Video: (videoId: string, videoElement: HTMLVideoElement) => VideoTrackerHandle;
+
+/**
+ * LandingTracker — Orquestador de sesión completa
+ * Inicializa y gestiona scroll tracking, click heatmap, section dwell time,
+ * form auto-tracking y sesión start/end.
+ * Framework-agnostic.
+ */
+
+declare class LandingTracker {
+    private config;
+    private isInitialized;
+    private sessionStartTime;
+    private scrollMilestonesReached;
+    private clicks;
+    private sectionTimers;
+    private observers;
+    private listeners;
+    /**
+     * Inicializa el tracking de la landing con la configuración dada.
+     */
+    init(config: LandingTrackerConfig): void;
+    /**
+     * Destruye el tracker y limpia todos los observers y listeners.
+     */
+    destroy(): void;
+    /** Trackear click en un CTA */
+    trackCTAClick(buttonName: string, section: string, additionalData?: Record<string, unknown>): void;
+    /** Trackear conversión */
+    trackConversion(type: string, value?: number, additionalData?: Record<string, unknown>): void;
+    /** Trackear click en FAQs */
+    trackFAQExpand(question: string, index: number): void;
+    /** Trackear click social */
+    trackSocialClick(platform: string, action: string): void;
+    /** Trackear click en imagen */
+    trackImageClick(imageName: string, section: string): void;
+    /** Trackear scroll a sección */
+    trackScrollTo(section: string): void;
+    /** Trackear share */
+    trackShare(platform: string, content: string): void;
+    /** Trackear descarga */
+    trackDownload(fileName: string, fileType: string): void;
+    /** Obtener datos de la sesión actual */
+    getSessionData(): {
+        duration: number;
+        clicks: number;
+        scrollMilestones: number[];
+    };
+    private captureInitialData;
+    private trackSessionStart;
+    private getEventName;
+    private pushGTMEvent;
+    private addListener;
+    private initScrollTracking;
+    private initCTATracking;
+    private initTimeTracking;
+    private initSectionTracking;
+    private initFormTracking;
+    private initClickHeatmap;
+}
+/**
+ * Factory function para crear un LandingTracker.
+ *
+ * @example
+ * ```ts
+ * const tracker = createLandingTracker({
+ *   pagePath: '/kin',
+ *   pageName: 'Kin Landing Page',
+ *   gtmId: 'GTM-5GMQNFMN',
+ * })
+ * // Al desmontar:
+ * tracker.destroy()
+ * ```
+ */
+declare const createLandingTracker: (config: LandingTrackerConfig) => LandingTracker;
+
+/**
+ * API Client — Cliente HTTP configurable para persistencia al backend.
+ * Framework-agnostic. Usa fetch nativo.
+ *
+ * @example
+ * ```ts
+ * import { initTrackingAPI } from '@metodokorexmk/tracking';
+ *
+ * initTrackingAPI({
+ *   baseUrl: 'https://api.korex.com/api/v1',
+ *   getAuthToken: () => localStorage.getItem('access_token'),
+ * });
+ * ```
+ */
+
+/**
+ * Inicializa el cliente HTTP para la capa de persistencia.
+ * Debe llamarse antes de usar funciones de lead submission, dwell time o queries.
+ */
+declare const initTrackingAPI: (config: TrackingAPIConfig) => void;
+/**
+ * Verifica si el API client ha sido inicializado.
+ */
+declare const isTrackingAPIInitialized: () => boolean;
+
+/**
+ * Lead Submission — Creación y actualización de leads en el backend.
+ * Migrado de lead-origin-detector.ts, framework-agnostic.
+ */
+
+/**
+ * Extrae todos los parámetros relevantes de la URL.
+ *
+ * @param url - URL opcional (si no se proporciona, usa window.location)
+ * @returns Objeto con todos los parámetros extraídos
+ */
+declare const extractUrlParams: (url?: string) => UrlParams;
+/**
+ * Detecta el origen del lead basándose en los parámetros de la URL.
+ * Facebook Ads: tiene fbclid O campaign_id
+ * Orgánico: tiene whatsapp Y NO tiene fbclid Y NO tiene campaign_id
+ */
+declare const detectLeadOrigin: (url?: string) => LeadOrigin;
+/**
+ * Construye el body de la petición según el tipo de origen.
+ */
+declare const buildTrackingRequestBody: (params: UrlParams, formData: LeadFormData, origin: LeadOrigin, options?: BuildRequestBodyOptions) => Record<string, unknown>;
+/**
+ * Envía el lead al endpoint correcto según su origen.
+ */
+declare const submitTrackingLead: (body: Record<string, unknown>, origin: LeadOrigin) => Promise<SubmitTrackingLeadResponse>;
+/**
+ * Función completa: detecta origen, construye body y envía el lead.
+ *
+ * @example
+ * ```ts
+ * const result = await submitLead(
+ *   { nombre: 'Juan', correo: 'juan@mail.com', telefono: '+34600...' },
+ *   { nameForm: 'Formulario Kin', videoCompleted: true },
+ * );
+ * ```
+ */
+declare const submitLead: (formData: LeadFormData, options?: BuildRequestBodyOptions, url?: string) => Promise<SubmitTrackingLeadResponse>;
+/**
+ * Actualiza un lead existente mediante PATCH.
+ */
+declare const updateTrackingLead: (trackingId: number | string, updates: Record<string, unknown>) => Promise<boolean>;
+/**
+ * Marca un lead como "WhatsApp enviado".
+ */
+declare const markWhatsAppSent: (leadId: number | string) => Promise<boolean>;
+/**
+ * Construye un msgForm como JSON stringificado.
+ */
+declare const buildMsgFormJSON: (mensaje: string, datosAdicionales?: Record<string, unknown>) => string;
+
+/**
+ * DwellTimeTracker — Tracking de tiempo de permanencia con envío periódico al backend.
+ * Migrado de dwell-time.ts (~960 líneas → ~280 líneas limpias).
+ * Framework-agnostic.
+ */
+
+/**
+ * Clase que mide el tiempo de permanencia del usuario en una página
+ * y lo envía periódicamente al backend de tracking.
+ *
+ * Características:
+ * - Envío automático cada 30 segundos
+ * - Pausa automática cuando la pestaña se oculta
+ * - sendBeacon en beforeunload para máxima confiabilidad
+ * - Retry de updates pendientes via sessionStorage
+ * - Tracking de video integrado (videoTimeWatched, videoCompleted)
+ */
+declare class DwellTimeTracker {
+    private startTime;
+    private trackingDataId;
+    private enabled;
+    private onSuccess?;
+    private onError?;
+    private intervalId;
+    private isSending;
+    private videoTimeWatched;
+    private videoCompleted;
+    private videoTrackingStopped;
+    private lastDwellTimeSent;
+    private lastVideoTimeSent;
+    private pausedTime;
+    private pauseStartTime;
+    private boundBeforeUnload;
+    private boundVisibilityChange;
+    constructor();
+    /**
+     * Inicia el tracking del tiempo de permanencia.
+     */
+    start(config: DwellTimeConfig): void;
+    /**
+     * Detiene el tracking y envía el tiempo acumulado.
+     */
+    stop(): void;
+    /**
+     * Obtiene el tiempo transcurrido en segundos (restando tiempo pausado).
+     */
+    getElapsedTime(): number;
+    /**
+     * Actualiza manualmente el tiempo del video.
+     * Llamar desde el VideoTracker u otros adaptadores.
+     */
+    updateVideoTime(videoTimeWatched: number, videoCompleted?: boolean): void;
+    /**
+     * Actualiza el trackingDataId (útil cuando se obtiene después del registro).
+     */
+    updateTrackingId(trackingDataId: number | string): void;
+    /**
+     * Limpia todos los listeners y timers.
+     */
+    destroy(): void;
+    private checkLocalStorageForId;
+    private sendDwellTime;
+    private handleBeforeUnload;
+    private handleVisibilityChange;
+    private sendDwellTimeWithBeacon;
+    private savePendingUpdate;
+    private retryPendingUpdates;
+    private clearPendingUpdate;
+    private cleanupListeners;
+    private cleanup;
+}
+declare const dwellTimeTracker: DwellTimeTracker;
+/**
+ * Inicia el tracking del tiempo de permanencia.
+ */
+declare const startDwellTimeTracking: (config: DwellTimeConfig) => void;
+/**
+ * Detiene el tracking y envía el tiempo acumulado.
+ */
+declare const stopDwellTimeTracking: () => void;
+
+/**
+ * Tracking Queries — Consultas GET al backend de tracking.
+ * Migrado de TrackingService.ts y LeadTrackingService.ts.
+ * Framework-agnostic.
+ */
+
+/**
+ * Obtiene los datos de un tracking lead por su ID.
+ *
+ * @example
+ * ```ts
+ * const tracking = await getTrackingById(123);
+ * console.log(tracking.videoTimeWatched, tracking.dwellTime);
+ * ```
+ */
+declare const getTrackingById: (trackingId: number | string) => Promise<TrackingLead>;
+/**
+ * Obtiene un lead con sus datos de tracking asociados.
+ * Procesa la respuesta para extraer videoVisto, tiempoReproducido, etc.
+ *
+ * @example
+ * ```ts
+ * const data = await getLeadWithTracking('456');
+ * console.log(data.videoVisto, data.dwellTime);
+ * ```
+ */
+declare const getLeadWithTracking: (leadId: string) => Promise<LeadTrackingData>;
+/**
+ * Genera un link de tracking para un funnel.
+ *
+ * @example
+ * ```ts
+ * const { link } = await generateTrackingLink(1, 'mi-dominio.com');
+ * ```
+ */
+declare const generateTrackingLink: (funnelId: number, customDomain: string) => Promise<{
+    link: string;
+}>;
+
+export { type BuildRequestBodyOptions, type ClickData, type DwellTimeConfig, DwellTimeTracker, LandingTracker, type LandingTrackerConfig, type LeadFormData, type LeadOrigin, type LeadTrackingData, type SessionSummary, type SubmitTrackingLeadResponse, type TrackingAPIConfig, type TrackingConfig, type TrackingEventData, type TrackingLead, type TrackingLeadResponse, type UTMParams, type UrlParams, type UseVideoTrackingOptions, type VideoStats, VideoTracker, type VideoTrackerHandle, type VideoTrackingState, type VideoUpdateCallback, type VisitorData, buildMsgFormJSON, buildTrackingRequestBody, captureUTMParams, captureUserIdFromURL, createLandingTracker, detectLeadOrigin, dwellTimeTracker, extractUrlParams, generateTrackingLink, getGATrackingId, getLeadWithTracking, getTrackingById, getUserId, getUserName, initGA, initTrackingAPI, injectGTMScript, isGAInitialized, isTrackingAPIInitialized, markWhatsAppSent, pushToDataLayer, reinitGA, resetAnalytics, setUserId, setUserName, startDwellTimeTracking, stopDwellTimeTracking, submitLead, submitTrackingLead, trackCTAClick, trackContactClick, trackConversion, trackDownload, trackEvent, trackFAQExpand, trackFormFieldComplete, trackFormStart, trackFormSubmit, trackFormValidationError, trackHTML5Video, trackImageClick, trackPageView, trackPricingCardClick, trackScrollTo, trackSectionClick, trackShare, trackSocialClick, trackTimeInSection, trackVoomlyByEmbedId, trackWistiaByMediaId, updateTrackingLead, videoTracker };