@agentuity/analytics 3.0.0-alpha.0

package/src/types.ts

@@ -0,0 +1,126 @@
+/**
+ * Analytics type definitions
+ */
+
+/** Scroll depth milestone event */
+export interface ScrollEvent {
+	depth: number;
+	timestamp: number;
+}
+
+/** Custom analytics event */
+export interface AnalyticsCustomEvent {
+	timestamp: number;
+	name: string;
+	data: string;
+}
+
+/** Geo location data from IP */
+export interface GeoLocation {
+	country?: string;
+	country_latitude?: string | number;
+	country_longitude?: string | number;
+	region?: string;
+	region_latitude?: string | number;
+	region_longitude?: string | number;
+	city?: string;
+	city_latitude?: string | number;
+	city_longitude?: string | number;
+	timezone?: string;
+	latitude?: string | number;
+	longitude?: string | number;
+}
+
+/** Page view data collected by the beacon */
+export interface PageViewData {
+	id: string;
+	timestamp: number;
+	timezone_offset: number;
+	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;
+	scroll_depth: number;
+	time_on_page: number;
+	scroll_events: ScrollEvent[];
+	custom_events: AnalyticsCustomEvent[];
+	load_time?: number;
+	dom_ready?: number;
+	ttfb?: number;
+	fcp?: number;
+	lcp?: number;
+	cls?: number;
+	inp?: number;
+	country?: string;
+	country_latitude?: number;
+	country_longitude?: number;
+	region?: string;
+	region_latitude?: number;
+	region_longitude?: number;
+	city?: string;
+	city_latitude?: number;
+	city_longitude?: number;
+	timezone?: string;
+	latitude?: number;
+	longitude?: number;
+	utm_source?: string;
+	utm_medium?: string;
+	utm_campaign?: string;
+	utm_term?: string;
+	utm_content?: string;
+	[key: string]: unknown;
+}
+
+/** Analytics configuration */
+export interface AnalyticsConfig {
+	/** Enable/disable tracking */
+	enabled: boolean;
+	/** Organization ID */
+	orgId: string;
+	/** Project ID */
+	projectId: string;
+	/** Running in development mode */
+	isDevmode?: boolean;
+	/** Track clicks on [data-analytics] elements */
+	trackClicks?: boolean;
+	/** Track scroll depth */
+	trackScroll?: boolean;
+	/** Track Web Vitals (FCP, LCP, CLS, INP) */
+	trackWebVitals?: boolean;
+	/** Track JS errors */
+	trackErrors?: boolean;
+	/** Track SPA navigation */
+	trackSPANavigation?: boolean;
+	/** Sampling rate (0-1) */
+	sampleRate?: number;
+	/** Custom collect endpoint */
+	endpoint?: string;
+}
+
+/** Analytics client API */
+export interface AnalyticsClient {
+	/** Track a custom event */
+	track: (name: string, properties?: Record<string, unknown>) => void;
+	/** Identify a user */
+	identify: (userId: string, traits?: Record<string, unknown>) => void;
+	/** Flush pending events */
+	flush: () => void;
+}
+
+/** Payload sent to collect endpoint */
+export interface AnalyticsPayload {
+	org_id: string;
+	project_id: string;
+	visitor_id: string;
+	user_id: string;
+	user_traits: Record<string, string>;
+	is_devmode: boolean;
+	pageview: PageViewData;
+}

package/src/util.ts

@@ -0,0 +1,123 @@
+/**
+ * Analytics utility functions
+ */
+
+import type { GeoLocation } from './types';
+
+/**
+ * Generate a unique ID
+ */
+export function generateId(): string {
+	if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+		return crypto.randomUUID();
+	}
+	return `${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+
+/**
+ * Safely stringify an object, handling circular references
+ */
+export function safeStringify(obj: unknown): string {
+	if (obj === undefined || obj === null) {
+		return '';
+	}
+	try {
+		const seen = new WeakSet();
+		return JSON.stringify(obj, (_key, value) => {
+			if (typeof value === 'object' && value !== null) {
+				if (seen.has(value)) {
+					return '[Circular]';
+				}
+				seen.add(value);
+			}
+			return value;
+		});
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		console.warn('[Agentuity Analytics] Failed to stringify:', message);
+		return `[unserializable: ${message}]`;
+	}
+}
+
+/**
+ * Strip query string from URL to prevent sensitive data leakage
+ */
+export function stripQueryString(url: string): string {
+	if (!url) return '';
+	try {
+		const parsed = new URL(url);
+		return parsed.origin + parsed.pathname;
+	} catch {
+		return url.split('?')[0] ?? url;
+	}
+}
+
+/**
+ * Get UTM parameters from URL
+ */
+export function getUTMParams(): Record<string, string> {
+	const params = new URLSearchParams(location.search);
+	const utm: Record<string, string> = {};
+	for (const key of ['utm_source', 'utm_medium', 'utm_campaign', 'utm_term', 'utm_content']) {
+		const value = params.get(key);
+		if (value) utm[key] = value;
+	}
+	return utm;
+}
+
+/**
+ * Get or create visitor ID from localStorage
+ */
+export function getVisitorId(): string {
+	try {
+		const stored = localStorage.getItem('agentuity_visitor_id');
+		if (stored) return stored;
+	} catch {
+		// localStorage not available
+	}
+	const id = 'vid_' + generateId();
+	try {
+		localStorage.setItem('agentuity_visitor_id', id);
+	} catch {
+		// localStorage not available
+	}
+	return id;
+}
+
+/**
+ * Get cached geo location
+ */
+export function getCachedGeo(): GeoLocation | null {
+	try {
+		const cached = sessionStorage.getItem('agentuity_geo');
+		if (cached) return JSON.parse(cached);
+	} catch {
+		// sessionStorage not available
+	}
+	return null;
+}
+
+/**
+ * Cache geo location
+ */
+export function setCachedGeo(geo: GeoLocation): void {
+	try {
+		sessionStorage.setItem('agentuity_geo', JSON.stringify(geo));
+	} catch {
+		// sessionStorage not available
+	}
+}
+
+/**
+ * Fetch geo location from service
+ */
+export async function fetchGeo(): Promise<GeoLocation | null> {
+	try {
+		const response = await fetch('https://agentuity.sh/location');
+		const geo = await response.json();
+		setCachedGeo(geo);
+		return geo;
+	} catch {
+		return getCachedGeo();
+	}
+}