@agentuity/frontend 0.0.111 → 0.1.0

package/src/analytics/collectors/clicks.ts

@@ -0,0 +1,100 @@
+import { createBaseEvent } from './pageview';
+import { queueEvent } from '../events';
+
+/**
+ * Initialize click tracking
+ * Tracks clicks on elements with data-analytics attribute
+ */
+export function initClickTracking(): void {
+	if (typeof document === 'undefined') {
+		return;
+	}
+
+	document.addEventListener(
+		'click',
+		(e) => {
+			const target = e.target as HTMLElement | null;
+			if (!target) return;
+
+			// Find closest element with data-analytics attribute
+			const analyticsElement = target.closest('[data-analytics]');
+			if (!analyticsElement) return;
+
+			const eventName = analyticsElement.getAttribute('data-analytics');
+			if (!eventName) return;
+
+			const event = createBaseEvent('click');
+			event.event_name = eventName;
+
+			// Collect additional data attributes
+			const eventData: Record<string, unknown> = {};
+			for (const attr of Array.from(analyticsElement.attributes)) {
+				if (attr.name.startsWith('data-analytics-')) {
+					const key = attr.name.replace('data-analytics-', '');
+					eventData[key] = attr.value;
+				}
+			}
+
+			// Add element info
+			eventData.tag = analyticsElement.tagName.toLowerCase();
+			if (analyticsElement.id) {
+				eventData.id = analyticsElement.id;
+			}
+			const text = (analyticsElement as HTMLElement).innerText?.slice(0, 100);
+			if (text) {
+				eventData.text = text;
+			}
+
+			if (Object.keys(eventData).length > 0) {
+				event.event_data = eventData;
+			}
+
+			queueEvent(event);
+		},
+		{ capture: true, passive: true }
+	);
+}
+
+/**
+ * Initialize outbound link tracking
+ */
+export function initOutboundLinkTracking(): void {
+	if (typeof document === 'undefined') {
+		return;
+	}
+
+	document.addEventListener(
+		'click',
+		(e) => {
+			const target = e.target as HTMLElement | null;
+			if (!target) return;
+
+			const link = target.closest('a');
+			if (!link) return;
+
+			const href = link.href;
+			if (!href) return;
+
+			// Check if it's an outbound link
+			try {
+				const url = new URL(href, window.location.origin);
+				if (url.hostname === window.location.hostname) {
+					return; // Same domain, not outbound
+				}
+
+				const event = createBaseEvent('outbound_link');
+				event.event_name = 'outbound_link';
+				event.event_data = {
+					href,
+					hostname: url.hostname,
+					text: link.innerText?.slice(0, 100) || '',
+				};
+
+				queueEvent(event);
+			} catch {
+				// Invalid URL, ignore
+			}
+		},
+		{ capture: true, passive: true }
+	);
+}

package/src/analytics/collectors/errors.ts

@@ -0,0 +1,49 @@
+import { createBaseEvent } from './pageview';
+import { queueEvent } from '../events';
+
+/**
+ * Initialize JavaScript error tracking
+ */
+export function initErrorTracking(): void {
+	if (typeof window === 'undefined') {
+		return;
+	}
+
+	// Handle uncaught errors
+	window.addEventListener('error', (e) => {
+		const event = createBaseEvent('error');
+		event.event_name = 'js_error';
+		event.event_data = {
+			message: e.message || 'Unknown error',
+			filename: e.filename || '',
+			lineno: e.lineno || 0,
+			colno: e.colno || 0,
+			stack: e.error?.stack?.slice(0, 1000) || '',
+		};
+
+		queueEvent(event);
+	});
+
+	// Handle unhandled promise rejections
+	window.addEventListener('unhandledrejection', (e) => {
+		const event = createBaseEvent('error');
+		event.event_name = 'unhandled_rejection';
+
+		let message = 'Unhandled Promise Rejection';
+		let stack = '';
+
+		if (e.reason instanceof Error) {
+			message = e.reason.message;
+			stack = e.reason.stack?.slice(0, 1000) || '';
+		} else if (typeof e.reason === 'string') {
+			message = e.reason;
+		}
+
+		event.event_data = {
+			message,
+			stack,
+		};
+
+		queueEvent(event);
+	});
+}

package/src/analytics/collectors/forms.ts

@@ -0,0 +1,64 @@
+import { createBaseEvent } from './pageview';
+import { queueEvent } from '../events';
+
+/**
+ * Initialize form submission tracking
+ */
+export function initFormTracking(): void {
+	if (typeof document === 'undefined') {
+		return;
+	}
+
+	document.addEventListener(
+		'submit',
+		(e) => {
+			const form = e.target as HTMLFormElement | null;
+			if (!form || form.tagName !== 'FORM') {
+				return;
+			}
+
+			const event = createBaseEvent('form_submit');
+			event.event_name = 'form_submit';
+
+			const eventData: Record<string, unknown> = {};
+
+			// Form identification
+			if (form.id) {
+				eventData.form_id = form.id;
+			}
+			if (form.name) {
+				eventData.form_name = form.name;
+			}
+			if (form.action) {
+				eventData.form_action = form.action;
+			}
+			eventData.form_method = form.method || 'get';
+
+			// Count form fields (don't capture values for privacy)
+			const inputs = form.querySelectorAll('input, select, textarea');
+			eventData.field_count = inputs.length;
+
+			// Check for common form types
+			const hasEmail = form.querySelector('input[type="email"]') !== null;
+			const hasPassword = form.querySelector('input[type="password"]') !== null;
+			const hasSearch = form.querySelector('input[type="search"]') !== null;
+
+			if (hasEmail && hasPassword) {
+				eventData.form_type = 'auth';
+			} else if (hasEmail) {
+				eventData.form_type = 'email';
+			} else if (hasSearch) {
+				eventData.form_type = 'search';
+			} else if (hasPassword) {
+				eventData.form_type = 'password';
+			} else {
+				eventData.form_type = 'other';
+			}
+
+			event.event_data = eventData;
+
+			queueEvent(event);
+		},
+		{ capture: true }
+	);
+}

package/src/analytics/collectors/pageview.ts

@@ -0,0 +1,76 @@
+import type { AnalyticsEvent } from '../types';
+import { queueEvent } from '../events';
+import { getUTMParams } from '../utils/utm';
+
+/**
+ * Create a base event with common properties
+ */
+export function createBaseEvent(eventType: AnalyticsEvent['event_type']): AnalyticsEvent {
+	const utm = getUTMParams();
+
+	return {
+		id: crypto.randomUUID
+			? crypto.randomUUID()
+			: `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+		timestamp: Date.now(),
+		timezone_offset: new Date().getTimezoneOffset(),
+
+		event_type: eventType,
+
+		url: window.location.href,
+		path: window.location.pathname,
+		referrer: document.referrer || '',
+		title: document.title || '',
+
+		screen_width: window.screen?.width || 0,
+		screen_height: window.screen?.height || 0,
+		viewport_width: window.innerWidth || 0,
+		viewport_height: window.innerHeight || 0,
+		device_pixel_ratio: window.devicePixelRatio || 1,
+		user_agent: navigator.userAgent || '',
+		language: navigator.language || '',
+
+		...utm,
+	};
+}
+
+/**
+ * Track a pageview event
+ */
+export function trackPageview(customPath?: string): void {
+	const event = createBaseEvent('pageview');
+
+	if (customPath) {
+		event.path = customPath;
+		event.url = window.location.origin + customPath;
+	}
+
+	// Add performance timing if available
+	if (typeof performance !== 'undefined') {
+		const timing = performance.getEntriesByType('navigation')[0] as
+			| PerformanceNavigationTiming
+			| undefined;
+		if (timing) {
+			event.load_time = Math.round(timing.loadEventEnd - timing.startTime);
+			event.dom_ready = Math.round(timing.domContentLoadedEventEnd - timing.startTime);
+			event.ttfb = Math.round(timing.responseStart - timing.requestStart);
+		}
+	}
+
+	queueEvent(event);
+}
+
+/**
+ * Initialize pageview tracking
+ * Tracks initial pageview when called
+ */
+export function initPageviewTracking(): void {
+	// Track initial pageview after DOM is ready
+	if (document.readyState === 'complete') {
+		trackPageview();
+	} else {
+		window.addEventListener('load', () => {
+			trackPageview();
+		});
+	}
+}

package/src/analytics/collectors/scroll.ts

@@ -0,0 +1,112 @@
+import { createBaseEvent } from './pageview';
+import { queueEvent } from '../events';
+
+const SCROLL_MILESTONES = [25, 50, 75, 100];
+let trackedMilestones: Set<number> = new Set();
+let maxScrollDepth = 0;
+let isScrollTrackingInitialized = false;
+let scrollHandler: (() => void) | null = null;
+
+/**
+ * Calculate current scroll depth percentage
+ */
+function getScrollDepth(): number {
+	if (typeof window === 'undefined' || typeof document === 'undefined') {
+		return 0;
+	}
+
+	const scrollTop = window.scrollY || document.documentElement.scrollTop;
+	const scrollHeight =
+		document.documentElement.scrollHeight - document.documentElement.clientHeight;
+
+	if (scrollHeight <= 0) {
+		return 100; // Page doesn't scroll
+	}
+
+	return Math.min(100, Math.round((scrollTop / scrollHeight) * 100));
+}
+
+/**
+ * Handle scroll event
+ */
+function handleScroll(): void {
+	const depth = getScrollDepth();
+
+	if (depth > maxScrollDepth) {
+		maxScrollDepth = depth;
+	}
+
+	// Check for milestone crossings
+	for (const milestone of SCROLL_MILESTONES) {
+		if (depth >= milestone && !trackedMilestones.has(milestone)) {
+			trackedMilestones.add(milestone);
+
+			const event = createBaseEvent('scroll');
+			event.event_name = `scroll_${milestone}`;
+			event.scroll_depth = milestone;
+
+			queueEvent(event);
+		}
+	}
+}
+
+/**
+ * Initialize scroll depth tracking
+ */
+export function initScrollTracking(): void {
+	if (typeof window === 'undefined') {
+		return;
+	}
+
+	if (isScrollTrackingInitialized) {
+		return;
+	}
+	isScrollTrackingInitialized = true;
+
+	// Reset on page load
+	trackedMilestones = new Set();
+	maxScrollDepth = 0;
+
+	// Throttled scroll handler
+	let ticking = false;
+	scrollHandler = () => {
+		if (!ticking) {
+			requestAnimationFrame(() => {
+				handleScroll();
+				ticking = false;
+			});
+			ticking = true;
+		}
+	};
+
+	window.addEventListener('scroll', scrollHandler, { passive: true });
+
+	// Check initial scroll position (for pages that load scrolled)
+	handleScroll();
+}
+
+/**
+ * Remove scroll tracking listener
+ */
+export function removeScrollTracking(): void {
+	if (scrollHandler) {
+		window.removeEventListener('scroll', scrollHandler);
+		scrollHandler = null;
+	}
+	isScrollTrackingInitialized = false;
+}
+
+/**
+ * Get max scroll depth (for time on page events)
+ */
+export function getMaxScrollDepth(): number {
+	return maxScrollDepth;
+}
+
+/**
+ * Reset tracked milestones (for SPA navigation)
+ */
+export function resetScrollTracking(): void {
+	trackedMilestones = new Set();
+	maxScrollDepth = 0;
+}

package/src/analytics/collectors/spa.ts

@@ -0,0 +1,60 @@
+import { trackPageview } from './pageview';
+
+let currentPath = '';
+let originalPushState: typeof history.pushState | null = null;
+let originalReplaceState: typeof history.replaceState | null = null;
+
+/**
+ * Handle URL change for SPA navigation
+ */
+function handleUrlChange(): void {
+	const newPath = window.location.pathname;
+	if (newPath !== currentPath) {
+		currentPath = newPath;
+		trackPageview(newPath);
+	}
+}
+
+/**
+ * Initialize SPA navigation tracking
+ * Hooks into history.pushState, history.replaceState, and popstate event
+ */
+export function initSPATracking(): void {
+	if (typeof window === 'undefined' || typeof history === 'undefined') {
+		return;
+	}
+
+	currentPath = window.location.pathname;
+
+	// Hook into history.pushState
+	originalPushState = history.pushState.bind(history);
+	history.pushState = function (...args) {
+		originalPushState?.apply(this, args);
+		handleUrlChange();
+	};
+
+	// Hook into history.replaceState
+	originalReplaceState = history.replaceState.bind(history);
+	history.replaceState = function (...args) {
+		originalReplaceState?.apply(this, args);
+		handleUrlChange();
+	};
+
+	// Listen for popstate (back/forward navigation)
+	window.addEventListener('popstate', handleUrlChange);
+}
+
+/**
+ * Cleanup SPA tracking (for testing)
+ */
+export function cleanupSPATracking(): void {
+	if (originalPushState) {
+		history.pushState = originalPushState;
+		originalPushState = null;
+	}
+	if (originalReplaceState) {
+		history.replaceState = originalReplaceState;
+		originalReplaceState = null;
+	}
+	window.removeEventListener('popstate', handleUrlChange);
+}

package/src/analytics/collectors/visibility.ts

@@ -0,0 +1,94 @@
+import { createBaseEvent } from './pageview';
+import { queueEvent } from '../events';
+import { getMaxScrollDepth } from './scroll';
+
+let pageEntryTime = 0;
+let hiddenTime = 0;
+let lastHiddenTimestamp = 0;
+let visibilityTrackingInitialized = false;
+let visibilityChangeHandler: (() => void) | null = null;
+
+/**
+ * Get total time spent on page (excluding hidden time)
+ */
+function getTimeOnPage(): number {
+	if (pageEntryTime === 0) {
+		return 0;
+	}
+
+	const totalTime = Date.now() - pageEntryTime;
+	return Math.max(0, totalTime - hiddenTime);
+}
+
+/**
+ * Initialize visibility tracking
+ * Tracks when user leaves/returns to the page
+ */
+export function initVisibilityTracking(): void {
+	if (typeof document === 'undefined') {
+		return;
+	}
+
+	if (visibilityTrackingInitialized) {
+		return;
+	}
+	visibilityTrackingInitialized = true;
+
+	pageEntryTime = Date.now();
+	hiddenTime = 0;
+	lastHiddenTimestamp = 0;
+
+	visibilityChangeHandler = () => {
+		if (document.visibilityState === 'hidden') {
+			lastHiddenTimestamp = Date.now();
+
+			// Track page leave with engagement metrics
+			const event = createBaseEvent('visibility');
+			event.event_name = 'page_hidden';
+			event.time_on_page = getTimeOnPage();
+			event.scroll_depth = getMaxScrollDepth();
+
+			queueEvent(event);
+		} else if (document.visibilityState === 'visible') {
+			// Calculate hidden duration
+			if (lastHiddenTimestamp > 0) {
+				hiddenTime += Date.now() - lastHiddenTimestamp;
+				lastHiddenTimestamp = 0;
+			}
+
+			const event = createBaseEvent('visibility');
+			event.event_name = 'page_visible';
+
+			queueEvent(event);
+		}
+	};
+
+	document.addEventListener('visibilitychange', visibilityChangeHandler);
+}
+
+/**
+ * Remove visibility tracking listener
+ */
+export function removeVisibilityTracking(): void {
+	if (visibilityChangeHandler) {
+		document.removeEventListener('visibilitychange', visibilityChangeHandler);
+		visibilityChangeHandler = null;
+	}
+	visibilityTrackingInitialized = false;
+}
+
+/**
+ * Reset visibility tracking (for SPA navigation)
+ */
+export function resetVisibilityTracking(): void {
+	pageEntryTime = Date.now();
+	hiddenTime = 0;
+	lastHiddenTimestamp = 0;
+}
+
+/**
+ * Get current time on page
+ */
+export function getCurrentTimeOnPage(): number {
+	return getTimeOnPage();
+}

package/src/analytics/collectors/webvitals.ts

@@ -0,0 +1,129 @@
+import { createBaseEvent } from './pageview';
+import { queueEvent, flushEvents } from '../events';
+
+/**
+ * Initialize Core Web Vitals tracking
+ * Uses PerformanceObserver to track LCP, FCP, CLS, INP
+ */
+export function initWebVitalsTracking(): void {
+	if (typeof window === 'undefined' || typeof PerformanceObserver === 'undefined') {
+		return;
+	}
+
+	// Track First Contentful Paint (FCP)
+	try {
+		const fcpObserver = new PerformanceObserver((list) => {
+			for (const entry of list.getEntries()) {
+				if (entry.name === 'first-contentful-paint') {
+					const event = createBaseEvent('web_vital');
+					event.event_name = 'fcp';
+					event.fcp = Math.round(entry.startTime);
+					queueEvent(event);
+					flushEvents();
+					fcpObserver.disconnect();
+				}
+			}
+		});
+		fcpObserver.observe({ type: 'paint', buffered: true });
+	} catch {
+		// PerformanceObserver not supported for this entry type
+	}
+
+	// Track Largest Contentful Paint (LCP)
+	try {
+		let lcpValue = 0;
+		const lcpObserver = new PerformanceObserver((list) => {
+			const entries = list.getEntries();
+			const lastEntry = entries[entries.length - 1];
+			if (lastEntry) {
+				lcpValue = lastEntry.startTime;
+			}
+		});
+		lcpObserver.observe({ type: 'largest-contentful-paint', buffered: true });
+
+		// Report LCP when page becomes hidden
+		document.addEventListener(
+			'visibilitychange',
+			() => {
+				if (document.visibilityState === 'hidden' && lcpValue > 0) {
+					const event = createBaseEvent('web_vital');
+					event.event_name = 'lcp';
+					event.lcp = Math.round(lcpValue);
+					queueEvent(event);
+					flushEvents();
+					lcpObserver.disconnect();
+				}
+			},
+			{ once: true }
+		);
+	} catch {
+		// PerformanceObserver not supported for this entry type
+	}
+
+	// Track Cumulative Layout Shift (CLS)
+	try {
+		let clsValue = 0;
+		const clsObserver = new PerformanceObserver((list) => {
+			for (const entry of list.getEntries()) {
+				const layoutShift = entry as PerformanceEntry & {
+					hadRecentInput?: boolean;
+					value?: number;
+				};
+				if (!layoutShift.hadRecentInput && layoutShift.value) {
+					clsValue += layoutShift.value;
+				}
+			}
+		});
+		clsObserver.observe({ type: 'layout-shift', buffered: true });
+
+		// Report CLS when page becomes hidden
+		document.addEventListener(
+			'visibilitychange',
+			() => {
+				if (document.visibilityState === 'hidden') {
+					const event = createBaseEvent('web_vital');
+					event.event_name = 'cls';
+					event.cls = Math.round(clsValue * 1000) / 1000; // Round to 3 decimal places
+					queueEvent(event);
+					flushEvents();
+					clsObserver.disconnect();
+				}
+			},
+			{ once: true }
+		);
+	} catch {
+		// PerformanceObserver not supported for this entry type
+	}
+
+	// Track Interaction to Next Paint (INP)
+	try {
+		let inpValue = 0;
+		const inpObserver = new PerformanceObserver((list) => {
+			for (const entry of list.getEntries()) {
+				const eventEntry = entry as PerformanceEntry & { duration?: number };
+				if (eventEntry.duration && eventEntry.duration > inpValue) {
+					inpValue = eventEntry.duration;
+				}
+			}
+		});
+		inpObserver.observe({ type: 'event', buffered: true });
+
+		// Report INP when page becomes hidden
+		document.addEventListener(
+			'visibilitychange',
+			() => {
+				if (document.visibilityState === 'hidden' && inpValue > 0) {
+					const event = createBaseEvent('web_vital');
+					event.event_name = 'inp';
+					event.inp = Math.round(inpValue);
+					queueEvent(event);
+					flushEvents();
+					inpObserver.disconnect();
+				}
+			},
+			{ once: true }
+		);
+	} catch {
+		// PerformanceObserver not supported for this entry type
+	}
+}