@agentuity/frontend 0.0.111 → 0.1.0

package/src/analytics/events.ts

@@ -0,0 +1,144 @@
+import type { AnalyticsEvent, AnalyticsBatchPayload, AnalyticsPageConfig } from './types';
+import { getVisitorId } from './utils/storage';
+
+const BATCH_SIZE = 10;
+const BATCH_TIMEOUT_MS = 5000;
+const COLLECT_ENDPOINT = '/_agentuity/webanalytics/collect';
+
+let eventQueue: AnalyticsEvent[] = [];
+let batchTimeout: ReturnType<typeof setTimeout> | null = null;
+let config: AnalyticsPageConfig | null = null;
+
+/**
+ * Initialize the event queue with config
+ */
+export function initEventQueue(pageConfig: AnalyticsPageConfig): void {
+	config = pageConfig;
+
+	// Flush on page unload
+	if (typeof window !== 'undefined') {
+		window.addEventListener('visibilitychange', () => {
+			if (document.visibilityState === 'hidden') {
+				flushEvents();
+			}
+		});
+
+		window.addEventListener('pagehide', () => {
+			flushEvents();
+		});
+	}
+}
+
+/**
+ * Queue an event for sending
+ */
+export function queueEvent(event: AnalyticsEvent): void {
+	if (!config) {
+		return;
+	}
+
+	// Apply sample rate (default: 1 = 100%)
+	const sampleRate = config.sampleRate ?? 1;
+	if (sampleRate < 1 && Math.random() > sampleRate) {
+		return;
+	}
+
+	// Check exclude patterns
+	const excludePatterns = config.excludePatterns ?? [];
+	if (excludePatterns.length > 0) {
+		const currentPath = window.location.pathname;
+		for (const pattern of excludePatterns) {
+			try {
+				if (new RegExp(pattern).test(currentPath)) {
+					return;
+				}
+			} catch {
+				// Invalid regex, skip
+			}
+		}
+	}
+
+	// Add global properties to event data
+	if (config.globalProperties && Object.keys(config.globalProperties).length > 0) {
+		event.event_data = {
+			...config.globalProperties,
+			...event.event_data,
+		};
+	}
+
+	eventQueue.push(event);
+
+	// Flush if batch size reached
+	if (eventQueue.length >= BATCH_SIZE) {
+		flushEvents();
+	} else if (!batchTimeout) {
+		// Set timeout for batch flush
+		batchTimeout = setTimeout(() => {
+			flushEvents();
+		}, BATCH_TIMEOUT_MS);
+	}
+}
+
+/**
+ * Flush all queued events
+ */
+export function flushEvents(): void {
+	if (batchTimeout) {
+		clearTimeout(batchTimeout);
+		batchTimeout = null;
+	}
+
+	if (eventQueue.length === 0 || !config) {
+		return;
+	}
+
+	const events = eventQueue;
+	eventQueue = [];
+
+	// In dev mode, log to console instead of sending
+	if (config.isDevmode) {
+		console.debug('[Agentuity Analytics] Events:', events);
+		return;
+	}
+
+	const payload: AnalyticsBatchPayload = {
+		org_id: config.orgId,
+		project_id: config.projectId,
+		session_id: config.sessionId,
+		thread_id: config.threadId,
+		visitor_id: getVisitorId(),
+		is_devmode: config.isDevmode,
+		events,
+	};
+
+	const body = JSON.stringify(payload);
+
+	// Use sendBeacon for reliable delivery
+	if (typeof navigator !== 'undefined' && navigator.sendBeacon) {
+		const sent = navigator.sendBeacon(COLLECT_ENDPOINT, body);
+		if (sent) {
+			return;
+		}
+	}
+
+	// Fallback to fetch with keepalive
+	if (typeof fetch !== 'undefined') {
+		fetch(COLLECT_ENDPOINT, {
+			method: 'POST',
+			headers: {
+				'Content-Type': 'application/json',
+			},
+			body,
+			keepalive: true,
+		}).catch(() => {
+			// Silent failure - analytics is best effort
+		});
+	}
+}
+
+/**
+ * Get current queue length (for testing)
+ */
+export function getQueueLength(): number {
+	return eventQueue.length;
+}

package/src/analytics/index.ts

@@ -0,0 +1,21 @@
+/**
+ * Web Analytics for Agentuity SDK applications
+ *
+ * This module provides client-side analytics tracking for web applications
+ * built with the Agentuity SDK.
+ */
+
+export { getAnalytics, track, initBeacon } from './beacon';
+
+export type {
+	AnalyticsClient,
+	AnalyticsEvent,
+	AnalyticsEventType,
+	AnalyticsBatchPayload,
+	AnalyticsPageConfig,
+} from './types';
+
+// Re-export utilities for advanced usage
+export { trackPageview, createBaseEvent } from './collectors/pageview';
+export { getVisitorId, isOptedOut, setOptOut } from './utils/storage';
+export { getUTMParams } from './utils/utm';

package/src/analytics/offline.ts

@@ -0,0 +1,163 @@
+import type { AnalyticsEvent } from './types';
+
+const DB_NAME = 'agentuity_analytics';
+const STORE_NAME = 'events';
+const DB_VERSION = 1;
+const MAX_QUEUE_SIZE = 1000;
+
+let db: IDBDatabase | null = null;
+let dbInitPromise: Promise<IDBDatabase | null> | null = null;
+
+/**
+ * Initialize IndexedDB for offline event storage
+ */
+async function initDB(): Promise<IDBDatabase | null> {
+	if (typeof indexedDB === 'undefined') {
+		return null;
+	}
+
+	return new Promise((resolve) => {
+		try {
+			const request = indexedDB.open(DB_NAME, DB_VERSION);
+
+			request.onerror = () => {
+				resolve(null);
+			};
+
+			request.onsuccess = () => {
+				resolve(request.result);
+			};
+
+			request.onupgradeneeded = (e) => {
+				const database = (e.target as IDBOpenDBRequest).result;
+				if (!database.objectStoreNames.contains(STORE_NAME)) {
+					database.createObjectStore(STORE_NAME, { keyPath: 'id' });
+				}
+			};
+		} catch {
+			resolve(null);
+		}
+	});
+}
+
+/**
+ * Get database instance
+ */
+async function getDB(): Promise<IDBDatabase | null> {
+	if (db) {
+		return db;
+	}
+
+	if (!dbInitPromise) {
+		dbInitPromise = initDB();
+	}
+
+	db = await dbInitPromise;
+	return db;
+}
+
+/**
+ * Store event in IndexedDB for offline persistence
+ */
+export async function storeOfflineEvent(event: AnalyticsEvent): Promise<void> {
+	const database = await getDB();
+	if (!database) {
+		return;
+	}
+
+	try {
+		const transaction = database.transaction(STORE_NAME, 'readwrite');
+		const store = transaction.objectStore(STORE_NAME);
+
+		// Check current count and evict old events if needed before adding
+		const count = await new Promise<number>((resolve) => {
+			const countRequest = store.count();
+			countRequest.onsuccess = () => resolve(countRequest.result);
+			countRequest.onerror = () => resolve(0);
+		});
+
+		if (count >= MAX_QUEUE_SIZE) {
+			// Evict oldest event (FIFO) before adding new one
+			await new Promise<void>((resolve) => {
+				const cursorRequest = store.openCursor();
+				cursorRequest.onsuccess = () => {
+					const cursor = cursorRequest.result;
+					if (cursor) {
+						const deleteRequest = cursor.delete();
+						deleteRequest.onsuccess = () => resolve();
+						deleteRequest.onerror = () => resolve();
+					} else {
+						resolve();
+					}
+				};
+				cursorRequest.onerror = () => resolve();
+			});
+		}
+
+		store.add(event);
+	} catch {
+		// Silent failure
+	}
+}
+
+/**
+ * Get all offline events and clear them
+ */
+export async function getAndClearOfflineEvents(): Promise<AnalyticsEvent[]> {
+	const database = await getDB();
+	if (!database) {
+		return [];
+	}
+
+	return new Promise((resolve) => {
+		try {
+			const transaction = database.transaction(STORE_NAME, 'readwrite');
+			const store = transaction.objectStore(STORE_NAME);
+
+			const events: AnalyticsEvent[] = [];
+			const request = store.openCursor();
+
+			request.onsuccess = () => {
+				const cursor = request.result;
+				if (cursor) {
+					events.push(cursor.value as AnalyticsEvent);
+					cursor.delete();
+					cursor.continue();
+				} else {
+					resolve(events);
+				}
+			};
+
+			request.onerror = () => {
+				resolve([]);
+			};
+		} catch {
+			resolve([]);
+		}
+	});
+}
+
+/**
+ * Check if we're online
+ */
+export function isOnline(): boolean {
+	if (typeof navigator === 'undefined') {
+		return true;
+	}
+	return navigator.onLine !== false;
+}
+
+/**
+ * Initialize offline support
+ * Listens for online event to flush queued events
+ */
+export function initOfflineSupport(flushCallback: () => void): void {
+	if (typeof window === 'undefined') {
+		return;
+	}
+
+	window.addEventListener('online', () => {
+		// Flush offline events when coming back online
+		flushCallback();
+	});
+}

package/src/analytics/types.ts

@@ -0,0 +1,139 @@
+/**
+ * Analytics event types
+ */
+export type AnalyticsEventType =
+	| 'pageview'
+	| 'click'
+	| 'scroll'
+	| 'visibility'
+	| 'error'
+	| 'custom'
+	| 'web_vital'
+	| 'form_submit'
+	| 'outbound_link';
+
+/**
+ * Analytics event sent to the collection endpoint
+ */
+export interface AnalyticsEvent {
+	id: string;
+	timestamp: number;
+	timezone_offset: number;
+
+	event_type: AnalyticsEventType;
+	event_name?: string;
+	event_data?: Record<string, unknown>;
+
+	url: string;
+	path: string;
+	referrer: string;
+	title: string;
+
+	screen_width: number;
+	screen_height: number;
+	viewport_width: number;
+	viewport_height: number;
+	device_pixel_ratio: number;
+	user_agent: string;
+	language: string;
+
+	load_time?: number;
+	dom_ready?: number;
+	ttfb?: number;
+	fcp?: number;
+	lcp?: number;
+	cls?: number;
+	inp?: number;
+
+	scroll_depth?: number;
+	time_on_page?: number;
+
+	utm_source?: string;
+	utm_medium?: string;
+	utm_campaign?: string;
+	utm_term?: string;
+	utm_content?: string;
+}
+
+/**
+ * Batch payload sent to /_agentuity/webanalytics/collect
+ */
+export interface AnalyticsBatchPayload {
+	org_id: string;
+	project_id: string;
+	session_id: string;
+	thread_id: string;
+	visitor_id: string;
+	is_devmode: boolean;
+	events: AnalyticsEvent[];
+}
+
+/**
+ * Configuration injected by SDK runtime into window.__AGENTUITY_ANALYTICS__
+ */
+export interface AnalyticsPageConfig {
+	enabled: boolean;
+	orgId: string;
+	projectId: string;
+	sessionId: string;
+	threadId: string;
+	isDevmode: boolean;
+
+	trackClicks?: boolean;
+	trackScroll?: boolean;
+	trackOutboundLinks?: boolean;
+	trackForms?: boolean;
+	trackWebVitals?: boolean;
+	trackErrors?: boolean;
+	trackSPANavigation?: boolean;
+	requireConsent?: boolean;
+	sampleRate?: number;
+	excludePatterns?: string[];
+	globalProperties?: Record<string, unknown>;
+}
+
+/**
+ * Public analytics client interface
+ */
+export interface AnalyticsClient {
+	/**
+	 * Track a custom event
+	 */
+	track(eventName: string, properties?: Record<string, unknown>): void;
+
+	/**
+	 * Identify the current user (sets visitor properties)
+	 */
+	identify(userId: string, traits?: Record<string, unknown>): void;
+
+	/**
+	 * Manually track a page view
+	 */
+	pageview(path?: string): void;
+
+	/**
+	 * Flush pending events immediately
+	 */
+	flush(): Promise<void>;
+
+	/**
+	 * Opt out of analytics
+	 */
+	optOut(): void;
+
+	/**
+	 * Opt back in to analytics
+	 */
+	optIn(): void;
+
+	/**
+	 * Check if analytics is currently enabled
+	 */
+	isEnabled(): boolean;
+}
+
+declare global {
+	interface Window {
+		__AGENTUITY_ANALYTICS__?: AnalyticsPageConfig;
+	}
+}

package/src/analytics/utils/storage.ts

@@ -0,0 +1,64 @@
+const VISITOR_ID_KEY = 'agentuity_visitor_id';
+const OPT_OUT_KEY = 'agentuity_analytics_optout';
+
+/**
+ * Generate a random UUID v4
+ */
+function generateUUID(): string {
+	if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+		return crypto.randomUUID();
+	}
+	return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+		const r = (Math.random() * 16) | 0;
+		const v = c === 'x' ? r : (r & 0x3) | 0x8;
+		return v.toString(16);
+	});
+}
+
+/**
+ * Get or create the visitor ID from localStorage
+ */
+export function getVisitorId(): string {
+	if (typeof localStorage === 'undefined') {
+		return generateUUID();
+	}
+
+	let visitorId = localStorage.getItem(VISITOR_ID_KEY);
+	if (!visitorId) {
+		visitorId = `vid_${generateUUID()}`;
+		try {
+			localStorage.setItem(VISITOR_ID_KEY, visitorId);
+		} catch {
+			// localStorage might be full or disabled
+		}
+	}
+	return visitorId;
+}
+
+/**
+ * Check if user has opted out
+ */
+export function isOptedOut(): boolean {
+	if (typeof localStorage === 'undefined') {
+		return false;
+	}
+	return localStorage.getItem(OPT_OUT_KEY) === 'true';
+}
+
+/**
+ * Set opt-out status
+ */
+export function setOptOut(optOut: boolean): void {
+	if (typeof localStorage === 'undefined') {
+		return;
+	}
+	try {
+		if (optOut) {
+			localStorage.setItem(OPT_OUT_KEY, 'true');
+		} else {
+			localStorage.removeItem(OPT_OUT_KEY);
+		}
+	} catch {
+		// localStorage might be full or disabled
+	}
+}

package/src/analytics/utils/utm.ts

@@ -0,0 +1,36 @@
+export interface UTMParams {
+	utm_source?: string;
+	utm_medium?: string;
+	utm_campaign?: string;
+	utm_term?: string;
+	utm_content?: string;
+}
+
+/**
+ * Extract UTM parameters from the current URL
+ */
+export function getUTMParams(): UTMParams {
+	if (typeof window === 'undefined') {
+		return {};
+	}
+
+	const params = new URLSearchParams(window.location.search);
+	const utm: UTMParams = {};
+
+	const source = params.get('utm_source');
+	if (source) utm.utm_source = source;
+
+	const medium = params.get('utm_medium');
+	if (medium) utm.utm_medium = medium;
+
+	const campaign = params.get('utm_campaign');
+	if (campaign) utm.utm_campaign = campaign;
+
+	const term = params.get('utm_term');
+	if (term) utm.utm_term = term;
+
+	const content = params.get('utm_content');
+	if (content) utm.utm_content = content;
+
+	return utm;
+}

package/src/index.ts

@@ -30,3 +30,21 @@ export type {
 	StreamClient,
 	EventHandler,
 } from './client/types';
+
+// Export analytics
+export {
+	getAnalytics,
+	track,
+	initBeacon,
+	trackPageview,
+	createBaseEvent,
+	getVisitorId,
+	isOptedOut,
+	setOptOut,
+	getUTMParams,
+	type AnalyticsClient,
+	type AnalyticsEvent,
+	type AnalyticsEventType,
+	type AnalyticsBatchPayload,
+	type AnalyticsPageConfig,
+} from './analytics';