@agentuity/frontend 0.0.110 → 0.0.112

package/dist/client/types.d.ts

@@ -86,26 +86,61 @@ export interface StreamClient {
      */
     cancel(): Promise<void>;
 }
+/**
+ * Options object for endpoints without path params (optional query support).
+ */
+export interface EndpointOptionsWithQuery<Input = unknown, Query = Record<string, string>> {
+    input?: Input;
+    query?: Query;
+}
+/**
+ * Additional options that can be passed after positional path params.
+ */
+export interface EndpointExtraOptions<Input = unknown, Query = Record<string, string>> {
+    input?: Input;
+    query?: Query;
+}
+/**
+ * Convert a path params object to a tuple of its value types.
+ * Used for positional argument typing.
+ * Note: For proper ordering, we rely on the generated PathParamsTuple type.
+ */
+export type PathParamsToTuple<P> = P extends readonly [infer First, ...infer Rest] ? [First, ...PathParamsToTuple<Rest>] : P extends readonly [] ? [] : string[];
 /**
  * API endpoint - callable function for regular HTTP calls.
+ * - Without path params: accepts input directly OR options object with query
+ * - With path params: accepts positional arguments followed by optional options object
+ *
+ * @example
+ * // No path params
+ * client.hello.post({ name: 'World' })
+ *
+ * // Single path param
+ * client.users.userId.get('123')
+ *
+ * // Multiple path params
+ * client.orgs.orgId.members.memberId.get('org-1', 'user-2')
+ *
+ * // With additional options
+ * client.users.userId.get('123', { query: { include: 'posts' } })
  */
-export type APIEndpoint<Input = unknown, Output = unknown> = (input?: Input) => Promise<Output>;
+export type APIEndpoint<Input = unknown, Output = unknown, PathParams = never, PathParamsTuple extends unknown[] = string[]> = [PathParams] extends [never] ? (inputOrOptions?: Input | EndpointOptionsWithQuery<Input>) => Promise<Output> : (...args: [...PathParamsTuple, options?: EndpointExtraOptions<Input>]) => Promise<Output>;
 /**
  * WebSocket endpoint - callable function that returns WebSocket client.
  */
-export type WebSocketEndpoint<Input = unknown, _Output = unknown> = (input?: Input) => WebSocketClient;
+export type WebSocketEndpoint<Input = unknown, _Output = unknown, PathParams = never, PathParamsTuple extends unknown[] = string[]> = [PathParams] extends [never] ? (inputOrOptions?: Input | EndpointOptionsWithQuery<Input>) => WebSocketClient : (...args: [...PathParamsTuple, options?: EndpointExtraOptions<Input>]) => WebSocketClient;
 /**
  * Server-Sent Events endpoint - callable function that returns EventStream client.
  */
-export type SSEEndpoint<Input = unknown, _Output = unknown> = (input?: Input) => EventStreamClient;
+export type SSEEndpoint<Input = unknown, _Output = unknown, PathParams = never, PathParamsTuple extends unknown[] = string[]> = [PathParams] extends [never] ? (inputOrOptions?: Input | EndpointOptionsWithQuery<Input>) => EventStreamClient : (...args: [...PathParamsTuple, options?: EndpointExtraOptions<Input>]) => EventStreamClient;
 /**
  * Streaming endpoint - callable function that returns Stream client.
  */
-export type StreamEndpoint<Input = unknown, _Output = unknown> = (input?: Input) => StreamClient;
+export type StreamEndpoint<Input = unknown, _Output = unknown, PathParams = never, PathParamsTuple extends unknown[] = string[]> = [PathParams] extends [never] ? (inputOrOptions?: Input | EndpointOptionsWithQuery<Input>) => StreamClient : (...args: [...PathParamsTuple, options?: EndpointExtraOptions<Input>]) => StreamClient;
 /**
  * Route endpoint - discriminated union based on route type.
  */
-export type RouteEndpoint<Input = unknown, Output = unknown, Type extends string = 'api'> = Type extends 'websocket' ? WebSocketEndpoint<Input, Output> : Type extends 'sse' ? SSEEndpoint<Input, Output> : Type extends 'stream' ? StreamEndpoint<Input, Output> : APIEndpoint<Input, Output>;
+export type RouteEndpoint<Input = unknown, Output = unknown, Type extends string = 'api', PathParams = never, PathParamsTuple extends unknown[] = []> = Type extends 'websocket' ? WebSocketEndpoint<Input, Output, PathParams, PathParamsTuple> : Type extends 'sse' ? SSEEndpoint<Input, Output, PathParams, PathParamsTuple> : Type extends 'stream' ? StreamEndpoint<Input, Output, PathParams, PathParamsTuple> : APIEndpoint<Input, Output, PathParams, PathParamsTuple>;
 /**
  * Recursively build the client proxy type from a RouteRegistry.
  */
@@ -114,6 +149,17 @@ export type Client<R> = {
         input: infer I;
         output: infer O;
         type: infer T;
+        params: infer P;
+        paramsTuple: infer PT;
+    } ? PT extends unknown[] ? RouteEndpoint<I, O, T extends string ? T : 'api', P, PT> : RouteEndpoint<I, O, T extends string ? T : 'api', P> : R[K] extends {
+        input: infer I;
+        output: infer O;
+        type: infer T;
+        params: infer P;
+    } ? RouteEndpoint<I, O, T extends string ? T : 'api', P> : R[K] extends {
+        input: infer I;
+        output: infer O;
+        type: infer T;
     } ? RouteEndpoint<I, O, T extends string ? T : 'api'> : R[K] extends {
         input: infer I;
         output: infer O;

package/dist/client/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,CAAC,CAAC;IAElC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAElE;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,IAAI,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,EAAE,EAAE;QACH,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,CAAC,OAAO,CAAC,GAAG,IAAI,CAAC;QACzD,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;QACpD,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QAC1D,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;KACrD,CAAC;IAEF;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAE1B;;OAEG;IACH,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IACjC;;OAEG;IACH,EAAE,EAAE;QACH,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,YAAY,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;QAC9D,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;QACpD,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;KACrD,CAAC;IAEF;;OAEG;IACH,KAAK,IAAI,IAAI,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B;;OAEG;IACH,EAAE,EAAE;QACH,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QAC1D,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QACpD,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;KACrD,CAAC;IAEF;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;AAEhG;;GAEG;AACH,MAAM,MAAM,iBAAiB,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CACnE,KAAK,CAAC,EAAE,KAAK,KACT,eAAe,CAAC;AAErB;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,iBAAiB,CAAC;AAEnG;;GAEG;AACH,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,YAAY,CAAC;AAEjG;;GAEG;AACH,MAAM,MAAM,aAAa,CACxB,KAAK,GAAG,OAAO,EACf,MAAM,GAAG,OAAO,EAChB,IAAI,SAAS,MAAM,GAAG,KAAK,IACxB,IAAI,SAAS,WAAW,GACzB,iBAAiB,CAAC,KAAK,EAAE,MAAM,CAAC,GAChC,IAAI,SAAS,KAAK,GACjB,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,GAC1B,IAAI,SAAS,QAAQ,GACpB,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,GAC7B,WAAW,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAEhC;;GAEG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;KACtB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,CAAA;KAAE,GAC5E,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,GACjD,CAAC,CAAC,CAAC,CAAC,SAAS;QAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAC/C,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,GAC1B,CAAC,CAAC,CAAC,CAAC,SAAS,MAAM,GAClB,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GACZ,KAAK;CACV,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -8,4 +8,5 @@ export { WebSocketManager, type MessageHandler as WebSocketMessageHandler, type
 export { EventStreamManager, type MessageHandler as EventStreamMessageHandler, type EventStreamCallbacks, type EventStreamManagerOptions, type EventStreamManagerState, } from './eventstream-manager';
 export { createClient } from './client/index';
 export type { Client, ClientOptions, RouteEndpoint, WebSocketClient, EventStreamClient, StreamClient, EventHandler, } from './client/types';
+export { getAnalytics, track, initBeacon, trackPageview, createBaseEvent, getVisitorId, isOptedOut, setOptOut, getUTMParams, type AnalyticsClient, type AnalyticsEvent, type AnalyticsEventType, type AnalyticsBatchPayload, type AnalyticsPageConfig, } from './analytics';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACjG,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EACN,gBAAgB,EAChB,KAAK,cAAc,IAAI,uBAAuB,EAC9C,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,kBAAkB,EAClB,KAAK,cAAc,IAAI,yBAAyB,EAChD,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,GAC5B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACX,MAAM,EACN,aAAa,EACb,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACZ,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,KAAK,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACnG,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,sBAAsB,EAAE,KAAK,gBAAgB,EAAE,MAAM,SAAS,CAAC;AACjG,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EACN,gBAAgB,EAChB,KAAK,cAAc,IAAI,uBAAuB,EAC9C,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,qBAAqB,GAC1B,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,kBAAkB,EAClB,KAAK,cAAc,IAAI,yBAAyB,EAChD,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,uBAAuB,GAC5B,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,YAAY,EACX,MAAM,EACN,aAAa,EACb,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,YAAY,EACZ,YAAY,GACZ,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACN,YAAY,EACZ,KAAK,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,EACZ,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,GACxB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -7,4 +7,6 @@ export { WebSocketManager, } from './websocket-manager';
 export { EventStreamManager, } from './eventstream-manager';
 // Export client implementation (local to this package)
 export { createClient } from './client/index';
+// Export analytics
+export { getAnalytics, track, initBeacon, trackPageview, createBaseEvent, getVisitorId, isOptedOut, setOptOut, getUTMParams, } from './analytics';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAgD,MAAM,aAAa,CAAC;AAEnG,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EACN,gBAAgB,GAKhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,kBAAkB,GAKlB,MAAM,uBAAuB,CAAC;AAE/B,uDAAuD;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AACtC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,EAAE,sBAAsB,EAAgD,MAAM,aAAa,CAAC;AAEnG,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EACN,gBAAgB,GAKhB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACN,kBAAkB,GAKlB,MAAM,uBAAuB,CAAC;AAE/B,uDAAuD;AACvD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAW9C,mBAAmB;AACnB,OAAO,EACN,YAAY,EACZ,KAAK,EACL,UAAU,EACV,aAAa,EACb,eAAe,EACf,YAAY,EACZ,UAAU,EACV,SAAS,EACT,YAAY,GAMZ,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/frontend",
-	"version": "0.0.110",
+	"version": "0.0.112",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -26,10 +26,10 @@
 		"prepublishOnly": "bun run clean && bun run build"
 	},
 	"dependencies": {
-		"@agentuity/core": "0.0.110"
+		"@agentuity/core": "0.0.112"
 	},
 	"devDependencies": {
-		"@agentuity/test-utils": "0.0.110",
+		"@agentuity/test-utils": "0.0.112",
 		"@types/bun": "latest",
 		"bun-types": "latest",
 		"typescript": "^5.9.0"

package/src/analytics/beacon.ts

@@ -0,0 +1,203 @@
+import type { AnalyticsPageConfig, AnalyticsClient } from './types';
+import { initEventQueue, queueEvent, flushEvents } from './events';
+import { initPageviewTracking, createBaseEvent, trackPageview } from './collectors/pageview';
+import { initSPATracking } from './collectors/spa';
+import { initClickTracking, initOutboundLinkTracking } from './collectors/clicks';
+import { initScrollTracking } from './collectors/scroll';
+import { initErrorTracking } from './collectors/errors';
+import { initVisibilityTracking } from './collectors/visibility';
+import { initFormTracking } from './collectors/forms';
+import { initWebVitalsTracking } from './collectors/webvitals';
+import { isOptedOut, setOptOut } from './utils/storage';
+import { initOfflineSupport, getAndClearOfflineEvents } from './offline';
+
+let initialized = false;
+let trackingStarted = false;
+let analyticsEnabled = true;
+let consentRequired = false;
+let consentGiven = false;
+
+/**
+ * Check if analytics should run
+ */
+function shouldTrack(): boolean {
+	if (!analyticsEnabled) return false;
+	if (isOptedOut()) return false;
+	if (consentRequired && !consentGiven) return false;
+	return true;
+}
+
+/**
+ * Initialize the analytics beacon
+ * Called automatically when the script loads
+ */
+export function initBeacon(): void {
+	if (initialized) {
+		return;
+	}
+
+	const config = window.__AGENTUITY_ANALYTICS__;
+	if (!config || !config.enabled) {
+		analyticsEnabled = false;
+		return;
+	}
+
+	initialized = true;
+	consentRequired = config.requireConsent ?? false;
+
+	// If consent is required and not given, wait for optIn
+	if (consentRequired && !consentGiven) {
+		return;
+	}
+
+	startTracking(config);
+}
+
+/**
+ * Start all tracking based on config
+ */
+function startTracking(config: AnalyticsPageConfig): void {
+	if (trackingStarted) {
+		return;
+	}
+	trackingStarted = true;
+
+	// Initialize event queue
+	initEventQueue(config);
+
+	// Initialize offline support
+	initOfflineSupport(async () => {
+		// Flush offline events when coming back online
+		const offlineEvents = await getAndClearOfflineEvents();
+		for (const event of offlineEvents) {
+			queueEvent(event);
+		}
+		flushEvents();
+	});
+
+	// Always track pageviews
+	initPageviewTracking();
+
+	// Initialize visibility tracking (for time on page)
+	initVisibilityTracking();
+
+	// Conditional tracking based on config (all default to true except requireConsent)
+	if (config.trackSPANavigation !== false) {
+		initSPATracking();
+	}
+
+	if (config.trackClicks !== false) {
+		initClickTracking();
+	}
+
+	if (config.trackOutboundLinks !== false) {
+		initOutboundLinkTracking();
+	}
+
+	if (config.trackScroll !== false) {
+		initScrollTracking();
+	}
+
+	if (config.trackErrors !== false) {
+		initErrorTracking();
+	}
+
+	if (config.trackForms !== false) {
+		initFormTracking();
+	}
+
+	if (config.trackWebVitals !== false) {
+		initWebVitalsTracking();
+	}
+}
+
+/**
+ * Create the analytics client API
+ */
+function createClient(): AnalyticsClient {
+	return {
+		track(eventName: string, properties?: Record<string, unknown>): void {
+			if (!shouldTrack()) return;
+
+			const event = createBaseEvent('custom');
+			event.event_name = eventName;
+			if (properties) {
+				event.event_data = properties;
+			}
+			queueEvent(event);
+		},
+
+		identify(userId: string, traits?: Record<string, unknown>): void {
+			if (!shouldTrack()) return;
+
+			const event = createBaseEvent('custom');
+			event.event_name = 'identify';
+			event.event_data = {
+				user_id: userId,
+				...traits,
+			};
+			queueEvent(event);
+		},
+
+		pageview(path?: string): void {
+			if (!shouldTrack()) return;
+			trackPageview(path);
+		},
+
+		async flush(): Promise<void> {
+			flushEvents();
+		},
+
+		optOut(): void {
+			setOptOut(true);
+			analyticsEnabled = false;
+		},
+
+		optIn(): void {
+			setOptOut(false);
+			analyticsEnabled = true;
+			consentGiven = true;
+
+			// If consent was required and now given, start tracking
+			if (consentRequired && !trackingStarted) {
+				const config = window.__AGENTUITY_ANALYTICS__;
+				if (config) {
+					startTracking(config);
+				}
+			}
+		},
+
+		isEnabled(): boolean {
+			return shouldTrack();
+		},
+	};
+}
+
+// Singleton client instance
+let clientInstance: AnalyticsClient | null = null;
+
+/**
+ * Get the analytics client instance
+ */
+export function getAnalytics(): AnalyticsClient {
+	if (!clientInstance) {
+		clientInstance = createClient();
+	}
+	return clientInstance;
+}
+
+/**
+ * Convenience function to track a custom event
+ */
+export function track(eventName: string, properties?: Record<string, unknown>): void {
+	getAnalytics().track(eventName, properties);
+}
+
+// Auto-initialize when script loads
+if (typeof window !== 'undefined') {
+	if (document.readyState === 'loading') {
+		document.addEventListener('DOMContentLoaded', initBeacon);
+	} else {
+		initBeacon();
+	}
+}

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();
+		});
+	}
+}