@tracelog/lib 0.0.1

package/dist/esm/handlers/click.handler.d.ts

@@ -0,0 +1,17 @@
+import { EventManager } from '../managers/event.manager';
+import { StateManager } from '../managers/state.manager';
+export declare class ClickHandler extends StateManager {
+    private readonly eventManager;
+    private clickHandler?;
+    constructor(eventManager: EventManager);
+    startTracking(): void;
+    stopTracking(): void;
+    private findTrackingElement;
+    private getRelevantClickElement;
+    private calculateClickCoordinates;
+    private extractTrackingData;
+    private generateClickData;
+    private getRelevantText;
+    private extractElementAttributes;
+    private createCustomEventData;
+}

package/dist/esm/handlers/click.handler.js

@@ -0,0 +1,195 @@
+import { HTML_DATA_ATTR_PREFIX, MAX_TEXT_LENGTH, INTERACTIVE_SELECTORS } from '../constants';
+import { EventType } from '../types';
+import { StateManager } from '../managers/state.manager';
+import { debugLog } from '../utils/logging';
+export class ClickHandler extends StateManager {
+    constructor(eventManager) {
+        super();
+        this.eventManager = eventManager;
+    }
+    startTracking() {
+        if (this.clickHandler) {
+            debugLog.debug('ClickHandler', 'Click tracking already active');
+            return;
+        }
+        debugLog.debug('ClickHandler', 'Starting click tracking');
+        this.clickHandler = (event) => {
+            const mouseEvent = event;
+            const target = mouseEvent.target;
+            const clickedElement = target instanceof HTMLElement
+                ? target
+                : target instanceof Node && target.parentElement instanceof HTMLElement
+                    ? target.parentElement
+                    : null;
+            if (!clickedElement) {
+                debugLog.warn('ClickHandler', 'Click target not found or not an element');
+                return;
+            }
+            debugLog.info('ClickHandler', '🖱️ Click detected on element', {
+                tagName: clickedElement.tagName,
+                className: clickedElement.className || 'none',
+                textContent: clickedElement.textContent?.slice(0, 50) ?? 'empty',
+            });
+            const trackingElement = this.findTrackingElement(clickedElement);
+            const relevantClickElement = this.getRelevantClickElement(clickedElement);
+            const coordinates = this.calculateClickCoordinates(mouseEvent, clickedElement);
+            if (trackingElement) {
+                const trackingData = this.extractTrackingData(trackingElement);
+                if (trackingData) {
+                    const attributeData = this.createCustomEventData(trackingData);
+                    this.eventManager.track({
+                        type: EventType.CUSTOM,
+                        custom_event: {
+                            name: attributeData.name,
+                            ...(attributeData.value && { metadata: { value: attributeData.value } }),
+                        },
+                    });
+                }
+            }
+            const clickData = this.generateClickData(clickedElement, relevantClickElement, coordinates);
+            this.eventManager.track({
+                type: EventType.CLICK,
+                click_data: clickData,
+            });
+        };
+        window.addEventListener('click', this.clickHandler, true);
+    }
+    stopTracking() {
+        if (this.clickHandler) {
+            window.removeEventListener('click', this.clickHandler, true);
+            this.clickHandler = undefined;
+        }
+    }
+    findTrackingElement(element) {
+        if (element.hasAttribute(`${HTML_DATA_ATTR_PREFIX}-name`)) {
+            return element;
+        }
+        const closest = element.closest(`[${HTML_DATA_ATTR_PREFIX}-name]`);
+        return closest || undefined;
+    }
+    getRelevantClickElement(element) {
+        for (const selector of INTERACTIVE_SELECTORS) {
+            try {
+                if (element.matches(selector)) {
+                    return element;
+                }
+            }
+            catch (error) {
+                debugLog.warn('ClickHandler', 'Invalid selector in interactive elements check', {
+                    selector,
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                });
+                continue;
+            }
+        }
+        for (const selector of INTERACTIVE_SELECTORS) {
+            try {
+                const parent = element.closest(selector);
+                if (parent) {
+                    return parent;
+                }
+            }
+            catch (error) {
+                debugLog.warn('ClickHandler', 'Invalid selector in parent element search', {
+                    selector,
+                    error: error instanceof Error ? error.message : 'Unknown error',
+                });
+                continue;
+            }
+        }
+        return element;
+    }
+    calculateClickCoordinates(event, element) {
+        const rect = element.getBoundingClientRect();
+        const x = event.clientX;
+        const y = event.clientY;
+        const relativeX = rect.width > 0 ? Math.max(0, Math.min(1, Number(((x - rect.left) / rect.width).toFixed(3)))) : 0;
+        const relativeY = rect.height > 0 ? Math.max(0, Math.min(1, Number(((y - rect.top) / rect.height).toFixed(3)))) : 0;
+        return { x, y, relativeX, relativeY };
+    }
+    extractTrackingData(trackingElement) {
+        const name = trackingElement.getAttribute(`${HTML_DATA_ATTR_PREFIX}-name`);
+        const value = trackingElement.getAttribute(`${HTML_DATA_ATTR_PREFIX}-value`);
+        if (!name) {
+            return undefined;
+        }
+        return {
+            element: trackingElement,
+            name,
+            ...(value && { value }),
+        };
+    }
+    generateClickData(clickedElement, relevantElement, coordinates) {
+        const { x, y, relativeX, relativeY } = coordinates;
+        const text = this.getRelevantText(clickedElement, relevantElement);
+        const attributes = this.extractElementAttributes(relevantElement);
+        const href = relevantElement.getAttribute('href');
+        const title = relevantElement.getAttribute('title');
+        const alt = relevantElement.getAttribute('alt');
+        const role = relevantElement.getAttribute('role');
+        const ariaLabel = relevantElement.getAttribute('aria-label');
+        const className = typeof relevantElement.className === 'string' ? relevantElement.className : String(relevantElement.className);
+        return {
+            x,
+            y,
+            relativeX,
+            relativeY,
+            tag: relevantElement.tagName.toLowerCase(),
+            ...(relevantElement.id && { id: relevantElement.id }),
+            ...(relevantElement.className && { class: className }),
+            ...(text && { text }),
+            ...(href && { href }),
+            ...(title && { title }),
+            ...(alt && { alt }),
+            ...(role && { role }),
+            ...(ariaLabel && { ariaLabel }),
+            ...(Object.keys(attributes).length > 0 && { dataAttributes: attributes }),
+        };
+    }
+    getRelevantText(clickedElement, relevantElement) {
+        const LARGE_CONTAINER_TAGS = ['main', 'section', 'article', 'body', 'html', 'header', 'footer', 'aside', 'nav'];
+        const clickedText = clickedElement.textContent?.trim() ?? '';
+        const relevantText = relevantElement.textContent?.trim() ?? '';
+        if (!clickedText && !relevantText) {
+            return '';
+        }
+        // Strategy 1: If clicked element has reasonable text, use it
+        if (clickedText && clickedText.length <= MAX_TEXT_LENGTH) {
+            return clickedText;
+        }
+        // Strategy 2: For large containers with excessive text, avoid using container text
+        const isLargeContainer = LARGE_CONTAINER_TAGS.includes(relevantElement.tagName.toLowerCase());
+        const hasExcessiveText = relevantText.length > MAX_TEXT_LENGTH * 2; // 510 chars
+        if (isLargeContainer && hasExcessiveText) {
+            // Use clicked element text if available and reasonable, otherwise empty
+            return clickedText && clickedText.length <= MAX_TEXT_LENGTH ? clickedText : '';
+        }
+        // Strategy 3: Use relevant text but truncate if needed
+        if (relevantText.length <= MAX_TEXT_LENGTH) {
+            return relevantText;
+        }
+        // Strategy 4: If clicked text is much shorter than relevant text, prefer clicked text
+        if (clickedText && clickedText.length < relevantText.length * 0.1) {
+            return clickedText.length <= MAX_TEXT_LENGTH ? clickedText : clickedText.slice(0, MAX_TEXT_LENGTH - 3) + '...';
+        }
+        // Fallback: truncate relevant text to exactly MAX_TEXT_LENGTH including ellipsis
+        return relevantText.slice(0, MAX_TEXT_LENGTH - 3) + '...';
+    }
+    extractElementAttributes(element) {
+        const commonAttributes = ['id', 'class', 'data-testid', 'aria-label', 'title', 'href', 'type', 'name'];
+        const result = {};
+        for (const attributeName of commonAttributes) {
+            const value = element.getAttribute(attributeName);
+            if (value) {
+                result[attributeName] = value;
+            }
+        }
+        return result;
+    }
+    createCustomEventData(trackingData) {
+        return {
+            name: trackingData.name,
+            ...(trackingData.value && { value: trackingData.value }),
+        };
+    }
+}

package/dist/esm/handlers/error.handler.d.ts

@@ -0,0 +1,15 @@
+import { EventManager } from '../managers/event.manager';
+import { StateManager } from '../managers/state.manager';
+export declare class ErrorHandler extends StateManager {
+    private readonly eventManager;
+    private readonly piiPatterns;
+    constructor(eventManager: EventManager);
+    startTracking(): void;
+    stopTracking(): void;
+    private setupErrorListener;
+    private setupUnhandledRejectionListener;
+    private readonly handleError;
+    private readonly handleUnhandledRejection;
+    private sanitizeText;
+    private shouldSample;
+}

package/dist/esm/handlers/error.handler.js

@@ -0,0 +1,93 @@
+import { StateManager } from '../managers/state.manager';
+import { ErrorType, EventType } from '../types';
+import { debugLog } from '../utils/logging';
+export class ErrorHandler extends StateManager {
+    constructor(eventManager) {
+        super();
+        this.piiPatterns = [
+            /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
+            /\b\d{3}[-.]?\d{3}[-.]?\d{4}\b/g,
+            /\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,
+            /\b[A-Z]{2}\d{2}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b/g,
+        ];
+        this.handleError = (event) => {
+            const config = this.get('config');
+            if (!this.shouldSample(config?.errorSampling ?? 0.1)) {
+                debugLog.debug('ErrorHandler', `Error not sampled, skipping (errorSampling: ${config?.errorSampling})`, {
+                    errorSampling: config?.errorSampling,
+                });
+                return;
+            }
+            debugLog.warn('ErrorHandler', `JavaScript error captured: ${event.message} (filename: ${event.filename}, lineno: ${event.lineno})`, {
+                message: event.message,
+                filename: event.filename,
+                lineno: event.lineno,
+            });
+            this.eventManager.track({
+                type: EventType.ERROR,
+                error_data: {
+                    type: ErrorType.JS_ERROR,
+                    message: this.sanitizeText(event.message || 'Unknown error'),
+                },
+            });
+        };
+        this.handleUnhandledRejection = (event) => {
+            const config = this.get('config');
+            if (!this.shouldSample(config?.errorSampling ?? 0.1)) {
+                debugLog.debug('ErrorHandler', 'Promise rejection not sampled, skipping', {
+                    errorSampling: config?.errorSampling,
+                });
+                return;
+            }
+            debugLog.warn('ErrorHandler', `Unhandled promise rejection captured (reason: ${typeof event.reason})`, {
+                reason: typeof event.reason,
+            });
+            let reason = 'Unknown rejection';
+            if (event.reason) {
+                if (typeof event.reason === 'string') {
+                    reason = event.reason;
+                }
+                else if (event.reason instanceof Error) {
+                    reason = event.reason.message || event.reason.toString();
+                }
+                else {
+                    reason = String(event.reason);
+                }
+            }
+            this.eventManager.track({
+                type: EventType.ERROR,
+                error_data: {
+                    type: ErrorType.PROMISE_REJECTION,
+                    message: this.sanitizeText(reason),
+                },
+            });
+        };
+        this.eventManager = eventManager;
+    }
+    startTracking() {
+        debugLog.debug('ErrorHandler', 'Starting error tracking');
+        this.setupErrorListener();
+        this.setupUnhandledRejectionListener();
+    }
+    stopTracking() {
+        debugLog.debug('ErrorHandler', 'Stopping error tracking');
+        window.removeEventListener('error', this.handleError);
+        window.removeEventListener('unhandledrejection', this.handleUnhandledRejection);
+    }
+    setupErrorListener() {
+        window.addEventListener('error', this.handleError);
+    }
+    setupUnhandledRejectionListener() {
+        window.addEventListener('unhandledrejection', this.handleUnhandledRejection);
+    }
+    sanitizeText(text) {
+        let sanitized = text;
+        for (const pattern of this.piiPatterns) {
+            sanitized = sanitized.replace(pattern, '[REDACTED]');
+        }
+        return sanitized;
+    }
+    shouldSample(rate) {
+        return Math.random() < rate;
+    }
+}

package/dist/esm/handlers/network.handler.d.ts

@@ -0,0 +1,16 @@
+import { EventManager } from '../managers/event.manager';
+import { StateManager } from '../managers/state.manager';
+export declare class NetworkHandler extends StateManager {
+    private readonly eventManager;
+    private readonly originalFetch;
+    private readonly originalXHROpen;
+    private readonly originalXHRSend;
+    constructor(eventManager: EventManager);
+    startTracking(): void;
+    stopTracking(): void;
+    private interceptFetch;
+    private interceptXHR;
+    private trackNetworkError;
+    private normalizeUrlForTracking;
+    private shouldSample;
+}

package/dist/esm/handlers/network.handler.js

@@ -0,0 +1,132 @@
+import { StateManager } from '../managers/state.manager';
+import { ErrorType, EventType } from '../types';
+import { normalizeUrl } from '../utils';
+import { debugLog } from '../utils/logging';
+export class NetworkHandler extends StateManager {
+    constructor(eventManager) {
+        super();
+        this.eventManager = eventManager;
+        this.originalFetch = window.fetch;
+        this.originalXHROpen = XMLHttpRequest.prototype.open;
+        this.originalXHRSend = XMLHttpRequest.prototype.send;
+    }
+    startTracking() {
+        debugLog.debug('NetworkHandler', 'Starting network error tracking');
+        this.interceptFetch();
+        this.interceptXHR();
+    }
+    stopTracking() {
+        debugLog.debug('NetworkHandler', 'Stopping network error tracking');
+        window.fetch = this.originalFetch;
+        XMLHttpRequest.prototype.open = this.originalXHROpen;
+        XMLHttpRequest.prototype.send = this.originalXHRSend;
+    }
+    interceptFetch() {
+        window.fetch = async (input, init) => {
+            const startTime = Date.now();
+            const url = typeof input === 'string' ? input : input.toString();
+            const method = init?.method ?? 'GET';
+            try {
+                const response = await this.originalFetch(input, init);
+                const duration = Date.now() - startTime;
+                if (!response.ok) {
+                    debugLog.debug('NetworkHandler', 'Fetch error detected', {
+                        method,
+                        url: this.normalizeUrlForTracking(url),
+                        status: response.status,
+                        statusText: response.statusText,
+                    });
+                    this.trackNetworkError(method.toUpperCase(), this.normalizeUrlForTracking(url), response.status, response.statusText, duration);
+                }
+                return response;
+            }
+            catch (error) {
+                const duration = Date.now() - startTime;
+                const errorMessage = error instanceof Error ? error.message : 'Network Error';
+                debugLog.debug('NetworkHandler', 'Fetch exception caught', {
+                    method,
+                    url: this.normalizeUrlForTracking(url),
+                    error: errorMessage,
+                });
+                this.trackNetworkError(method.toUpperCase(), this.normalizeUrlForTracking(url), undefined, errorMessage, duration);
+                throw error;
+            }
+        };
+    }
+    interceptXHR() {
+        const trackNetworkError = this.trackNetworkError.bind(this);
+        const normalizeUrlForTracking = this.normalizeUrlForTracking.bind(this);
+        const originalXHROpen = this.originalXHROpen;
+        const originalXHRSend = this.originalXHRSend;
+        XMLHttpRequest.prototype.open = function (method, url, async, user, password) {
+            const asyncMode = async ?? true;
+            const extendedThis = this;
+            extendedThis._tracelogStartTime = Date.now();
+            extendedThis._tracelogMethod = method.toUpperCase();
+            extendedThis._tracelogUrl = url.toString();
+            return originalXHROpen.call(this, method, url, asyncMode, user, password);
+        };
+        XMLHttpRequest.prototype.send = function (body) {
+            const xhr = this;
+            const startTime = xhr._tracelogStartTime ?? Date.now();
+            const method = xhr._tracelogMethod ?? 'GET';
+            const url = xhr._tracelogUrl ?? '';
+            const originalOnReadyStateChange = xhr.onreadystatechange;
+            xhr.onreadystatechange = (ev) => {
+                if (xhr.readyState === XMLHttpRequest.DONE) {
+                    const duration = Date.now() - startTime;
+                    if (xhr.status === 0 || xhr.status >= 400) {
+                        const statusText = xhr.statusText || 'Request Failed';
+                        debugLog.debug('NetworkHandler', 'XHR error detected', {
+                            method,
+                            url: normalizeUrlForTracking(url),
+                            status: xhr.status,
+                            statusText,
+                        });
+                        trackNetworkError(method, normalizeUrlForTracking(url), xhr.status, statusText, duration);
+                    }
+                }
+                if (originalOnReadyStateChange) {
+                    return originalOnReadyStateChange.call(xhr, ev);
+                }
+            };
+            return originalXHRSend.call(this, body);
+        };
+    }
+    trackNetworkError(method, url, status, statusText, duration) {
+        const config = this.get('config');
+        if (!this.shouldSample(config?.errorSampling ?? 0.1)) {
+            debugLog.debug('NetworkHandler', `Network error not sampled, skipping (errorSampling: ${config?.errorSampling}, method: ${method}, url: ${url})`, {
+                errorSampling: config?.errorSampling,
+                method,
+                url,
+            });
+            return;
+        }
+        debugLog.warn('NetworkHandler', `Network error tracked: ${method} ${url} (status: ${status}, statusText: ${statusText}, duration: ${duration}ms)`, { method, url, status, statusText, duration });
+        this.eventManager.track({
+            type: EventType.ERROR,
+            error_data: {
+                type: ErrorType.NETWORK_ERROR,
+                message: statusText,
+                method,
+                url,
+                status,
+                statusText,
+                duration,
+            },
+        });
+    }
+    normalizeUrlForTracking(url) {
+        try {
+            const config = this.get('config');
+            return normalizeUrl(url, config?.sensitiveQueryParams);
+        }
+        catch {
+            return url;
+        }
+    }
+    shouldSample(rate) {
+        return Math.random() < rate;
+    }
+}

package/dist/esm/handlers/page-view.handler.d.ts

@@ -0,0 +1,15 @@
+import { StateManager } from '../managers/state.manager';
+import { EventManager } from '../managers/event.manager';
+export declare class PageViewHandler extends StateManager {
+    private readonly eventManager;
+    private readonly onTrack;
+    private originalPushState?;
+    private originalReplaceState?;
+    constructor(eventManager: EventManager, onTrack: () => void);
+    startTracking(): void;
+    stopTracking(): void;
+    private patchHistory;
+    private readonly trackCurrentPage;
+    private trackInitialPageView;
+    private extractPageViewData;
+}

package/dist/esm/handlers/page-view.handler.js

@@ -0,0 +1,79 @@
+import { EventType } from '../types';
+import { normalizeUrl } from '../utils';
+import { StateManager } from '../managers/state.manager';
+import { debugLog } from '../utils/logging';
+export class PageViewHandler extends StateManager {
+    constructor(eventManager, onTrack) {
+        super();
+        this.trackCurrentPage = () => {
+            const rawUrl = window.location.href;
+            const normalizedUrl = normalizeUrl(rawUrl, this.get('config').sensitiveQueryParams);
+            if (this.get('pageUrl') !== normalizedUrl) {
+                const fromUrl = this.get('pageUrl');
+                debugLog.debug('PageViewHandler', 'Page navigation detected', { from: fromUrl, to: normalizedUrl });
+                this.set('pageUrl', normalizedUrl);
+                this.eventManager.track({
+                    type: EventType.PAGE_VIEW,
+                    page_url: this.get('pageUrl'),
+                    from_page_url: fromUrl,
+                    ...(this.extractPageViewData() && { page_view: this.extractPageViewData() }),
+                });
+                this.onTrack();
+            }
+        };
+        this.eventManager = eventManager;
+        this.onTrack = onTrack;
+    }
+    startTracking() {
+        debugLog.debug('PageViewHandler', 'Starting page view tracking');
+        this.trackInitialPageView();
+        this.trackCurrentPage();
+        window.addEventListener('popstate', this.trackCurrentPage);
+        window.addEventListener('hashchange', this.trackCurrentPage);
+        this.patchHistory('pushState');
+        this.patchHistory('replaceState');
+    }
+    stopTracking() {
+        debugLog.debug('PageViewHandler', 'Stopping page view tracking');
+        window.removeEventListener('popstate', this.trackCurrentPage);
+        window.removeEventListener('hashchange', this.trackCurrentPage);
+        if (this.originalPushState) {
+            window.history.pushState = this.originalPushState;
+        }
+        if (this.originalReplaceState) {
+            window.history.replaceState = this.originalReplaceState;
+        }
+    }
+    patchHistory(method) {
+        if (method === 'pushState' && !this.originalPushState) {
+            this.originalPushState = window.history.pushState;
+        }
+        else if (method === 'replaceState' && !this.originalReplaceState) {
+            this.originalReplaceState = window.history.replaceState;
+        }
+        const original = window.history[method];
+        window.history[method] = (...args) => {
+            original.apply(window.history, args);
+            this.trackCurrentPage();
+        };
+    }
+    trackInitialPageView() {
+        this.eventManager.track({
+            type: EventType.PAGE_VIEW,
+            page_url: this.get('pageUrl'),
+            ...(this.extractPageViewData() && { page_view: this.extractPageViewData() }),
+        });
+        this.onTrack();
+    }
+    extractPageViewData() {
+        const location = window.location;
+        const data = {
+            ...(document.referrer && { referrer: document.referrer }),
+            ...(document.title && { title: document.title }),
+            ...(location.pathname && { pathname: location.pathname }),
+            ...(location.search && { search: location.search }),
+            ...(location.hash && { hash: location.hash }),
+        };
+        return Object.values(data).some((value) => !!value) ? data : undefined;
+    }
+}

package/dist/esm/handlers/performance.handler.d.ts

@@ -0,0 +1,19 @@
+import { EventManager } from '../managers/event.manager';
+import { StateManager } from '../managers/state.manager';
+export declare class PerformanceHandler extends StateManager {
+    private readonly eventManager;
+    private readonly reportedByNav;
+    private readonly observers;
+    private lastLongTaskSentAt;
+    constructor(eventManager: EventManager);
+    startTracking(): Promise<void>;
+    stopTracking(): void;
+    private observeWebVitalsFallback;
+    private initWebVitals;
+    private reportTTFB;
+    private observeLongTasks;
+    private sendVital;
+    private trackWebVital;
+    private getNavigationId;
+    private safeObserve;
+}