@agentuity/frontend 0.0.110 → 0.0.112

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/client/index.ts

@@ -24,6 +24,40 @@ function resolveHeaders(
 	return typeof headers === 'function' ? headers() : headers;
 }
 
+/**
+ * Escape special regex characters in a string.
+ */
+function escapeRegExp(str: string): string {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Substitute path parameters in a URL path template.
+ * E.g., '/api/users/:id' with { id: '123' } becomes '/api/users/123'
+ */
+function substitutePathParams(pathTemplate: string, pathParams?: Record<string, string>): string {
+	if (!pathParams) return pathTemplate;
+
+	let result = pathTemplate;
+	for (const [key, value] of Object.entries(pathParams)) {
+		const escapedKey = escapeRegExp(key);
+		result = result.replace(new RegExp(`:${escapedKey}\\??`, 'g'), encodeURIComponent(value));
+		result = result.replace(new RegExp(`\\*${escapedKey}`, 'g'), encodeURIComponent(value));
+	}
+	return result;
+}
+
+/**
+ * Build URL with query params.
+ */
+function buildUrlWithQuery(baseUrl: string, path: string, query?: Record<string, string>): string {
+	const url = `${baseUrl}${path}`;
+	if (!query || Object.keys(query).length === 0) return url;
+
+	const params = new URLSearchParams(query);
+	return `${url}?${params.toString()}`;
+}
+
 /**
  * Create a type-safe API client from a RouteRegistry.
  *
@@ -76,37 +110,97 @@ export function createClient<R>(options: ClientOptions = {}, metadata?: unknown)
 			if (isTerminalMethod && currentPath.length >= 1) {
 				const method = prop;
 				const pathSegments = currentPath;
-				const urlPath = '/api/' + pathSegments.join('/');
 
-				// Determine route type
+				// Look up route metadata
 				let routeType = 'api';
+				let routePath: string | undefined;
+				// eslint-disable-next-line @typescript-eslint/no-explicit-any
+				let metaNode: any = metadata;
+
 				if (isStreamMethod) {
 					// Stream methods directly specify the route type
 					if (method === 'websocket') routeType = 'websocket';
 					else if (method === 'eventstream') routeType = 'sse';
 					else if (method === 'stream') routeType = 'stream';
-				} else if (metadata) {
-					// Look up route type from metadata for HTTP methods
-					// eslint-disable-next-line @typescript-eslint/no-explicit-any
-					let metaNode: any = metadata;
+				}
+
+				if (metadata) {
 					for (const segment of pathSegments) {
 						if (metaNode && typeof metaNode === 'object') {
 							metaNode = metaNode[segment];
 						}
 					}
-					if (metaNode && typeof metaNode === 'object' && metaNode[method]?.type) {
-						routeType = metaNode[method].type;
+					if (metaNode && typeof metaNode === 'object' && metaNode[method]) {
+						if (metaNode[method].type) {
+							routeType = metaNode[method].type;
+						}
+						if (metaNode[method].path) {
+							routePath = metaNode[method].path;
+						}
 					}
 				}
 
-				return (input?: unknown) => {
+				// Fallback URL path if no metadata
+				const fallbackPath = '/api/' + pathSegments.join('/');
+
+				return (...args: unknown[]) => {
 					const resolvedBaseUrl = resolveBaseUrl(baseUrl);
 					const resolvedHeaders = resolveHeaders(defaultHeaders);
 
+					// Get path param names from metadata if available
+					// eslint-disable-next-line @typescript-eslint/no-explicit-any
+					const pathParamNames: string[] | undefined = (metaNode as any)?.[method]?.pathParams;
+					const hasPathParams = pathParamNames && pathParamNames.length > 0;
+
+					let pathParams: Record<string, string> | undefined;
+					let input: unknown;
+					let query: Record<string, string> | undefined;
+
+					if (hasPathParams) {
+						// Route has path params - positional arguments API
+						// Args are: param1, param2, ..., [options?]
+						// Example: client.user.get('123', 12) or client.user.get('123', 12, { query: {...} })
+						pathParams = {};
+
+						for (let i = 0; i < pathParamNames.length; i++) {
+							const arg = args[i];
+							if (arg === undefined || arg === null) {
+								throw new Error(
+									`Missing required path parameter '${pathParamNames[i]}' at position ${i + 1}. ` +
+										`Expected ${pathParamNames.length} path parameter(s): ${pathParamNames.join(', ')}`
+								);
+							}
+							pathParams[pathParamNames[i]] = String(arg);
+						}
+
+						// Check if there's an options object after the path params
+						const optionsArg = args[pathParamNames.length];
+						if (optionsArg && typeof optionsArg === 'object') {
+							// eslint-disable-next-line @typescript-eslint/no-explicit-any
+							const opts = optionsArg as any;
+							input = opts.input;
+							query = opts.query;
+						}
+					} else {
+						// No path params - use existing behavior
+						const options = args[0];
+						// eslint-disable-next-line @typescript-eslint/no-explicit-any
+						const opts = options as any;
+						const isOptionsObject =
+							opts && typeof opts === 'object' && ('input' in opts || 'query' in opts);
+
+						input = isOptionsObject ? opts.input : options;
+						query = isOptionsObject ? opts.query : undefined;
+					}
+
+					// Substitute path params in the route path
+					const basePath = routePath || fallbackPath;
+					const urlPath = substitutePathParams(basePath, pathParams);
+
 					// WebSocket endpoint
 					if (routeType === 'websocket') {
 						const wsBaseUrl = resolvedBaseUrl.replace(/^http/, 'ws');
-						const wsUrl = `${wsBaseUrl}${urlPath}`;
+						const wsUrl = buildUrlWithQuery(wsBaseUrl, urlPath, query);
 						const ws = createWebSocketClient(wsUrl);
 						if (input) {
 							ws.on('open', () => ws.send(input));
@@ -116,9 +210,7 @@ export function createClient<R>(options: ClientOptions = {}, metadata?: unknown)
 
 					// SSE endpoint
 					if (routeType === 'sse') {
-						const sseUrl = `${resolvedBaseUrl}${urlPath}`;
-						// Note: Native EventSource doesn't support custom headers
-						// For auth, use withCredentials or consider fetch-based alternatives like @microsoft/fetch-event-source
+						const sseUrl = buildUrlWithQuery(resolvedBaseUrl, urlPath, query);
 						return createEventStreamClient(sseUrl, {
 							withCredentials: Object.keys(resolvedHeaders).length > 0,
 						});
@@ -126,7 +218,8 @@ export function createClient<R>(options: ClientOptions = {}, metadata?: unknown)
 
 					// Stream endpoint
 					if (routeType === 'stream') {
-						return fetch(`${resolvedBaseUrl}${urlPath}`, {
+						const streamUrl = buildUrlWithQuery(resolvedBaseUrl, urlPath, query);
+						return fetch(streamUrl, {
 							method: method.toUpperCase(),
 							headers: { 'Content-Type': contentType, ...resolvedHeaders },
 							body: input ? JSON.stringify(input) : undefined,
@@ -138,7 +231,8 @@ export function createClient<R>(options: ClientOptions = {}, metadata?: unknown)
 					}
 
 					// Regular API endpoint
-					return fetch(`${resolvedBaseUrl}${urlPath}`, {
+					const apiUrl = buildUrlWithQuery(resolvedBaseUrl, urlPath, query);
+					return fetch(apiUrl, {
 						method: method.toUpperCase(),
 						headers: { 'Content-Type': contentType, ...resolvedHeaders },
 						body: method.toUpperCase() !== 'GET' && input ? JSON.stringify(input) : undefined,