@alpic-ai/insights 1.156.0 → 1.157.0

package/dist/react/index.d.mts

@@ -1,24 +1,67 @@
 import { ReactNode } from "react";
+//#region src/react/analytics-transport.d.ts
+interface AnalyticsEvent {
+  name: string;
+  timestamp: number;
+  message?: string;
+  properties?: Record<string, unknown>;
+  duration?: number;
+  isError?: boolean;
+  error?: string;
+}
+//#endregion
 //#region src/react/analytics-client.d.ts
 interface CaptureOptions {
   message?: string;
   properties?: Record<string, unknown>;
+  /** Duration of the operation the event describes, in milliseconds. */
+  duration?: number;
+  isError?: boolean;
+  error?: string;
 }
+/** Inspect, transform, or drop (return `null`) each event before it is buffered for delivery. */
+type BeforeSend = (event: AnalyticsEvent) => AnalyticsEvent | null;
 //#endregion
 //#region src/react/alpic-analytics.d.ts
 interface Analytics {
   /** Queue a custom widget event for delivery to Alpic Analytics. */
   capture: (name: string, options?: CaptureOptions) => void;
 }
+/** Toggles for the SDK's built-in event capture. Lifecycle and errors are on by default; interactions are opt-in. */
+interface AutoCaptureOptions {
+  lifecycle?: boolean;
+  errors?: boolean;
+  interactions?: boolean;
+}
+interface AlpicAnalyticsProps {
+  children?: ReactNode;
+  /** Inspect, transform, or drop each event before delivery. Runs synchronously in `capture`. */
+  beforeSend?: BeforeSend;
+  autoCapture?: AutoCaptureOptions;
+}
 /**
  * Provides Alpic Analytics to descendant components and configures itself from the widget host.
  * Wrap the widget once, then call `useAnalytics()` from components that capture events.
  * Events captured before configuration is available are buffered automatically.
  */
-declare function AlpicAnalytics({ children }: {
-  children?: ReactNode;
-}): import("react").JSX.Element;
+declare function AlpicAnalytics({ children, beforeSend, autoCapture }: AlpicAnalyticsProps): import("react").JSX.Element;
 /** Returns the analytics client from the nearest `AlpicAnalytics` provider. */
 declare function useAnalytics(): Analytics;
 //#endregion
-export { AlpicAnalytics, type Analytics, type CaptureOptions, useAnalytics };
+//#region src/react/auto-capture.d.ts
+/**
+ * Reserved auto-capture event names. The `$` prefix marks events emitted by the SDK itself
+ * (lifecycle, errors, interactions) so the analytics UI can distinguish them from custom
+ * `capture()` calls. Keep in sync with the server-side reserved namespace.
+ */
+declare const AUTO_EVENT: {
+  readonly loaded: "$loaded";
+  readonly visible: "$visible";
+  readonly hidden: "$hidden";
+  readonly closed: "$closed";
+  readonly error: "$error";
+};
+/** Public DOM contract for declarative interaction capture: the attribute value is the event name. */
+declare const INTERACTION_ATTRIBUTE = "data-alpic-event";
+//#endregion
+export { AUTO_EVENT, AlpicAnalytics, type AlpicAnalyticsProps, type Analytics, type AutoCaptureOptions, type BeforeSend, type CaptureOptions, INTERACTION_ATTRIBUTE, useAnalytics };

package/dist/react/index.mjs

@@ -1,4 +1,4 @@
-import { createContext, useContext, useEffect, useState } from "react";
+import { createContext, useContext, useEffect, useRef, useState } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/react/analytics-transport.ts
 function postAnalyticsBatch(ingestUrl, events) {
@@ -12,9 +12,13 @@ function postAnalyticsBatch(ingestUrl, events) {
 const FLUSH_DELAY_MS = 2e3;
 var AnalyticsClient = class {
 	events = [];
+	beforeSend;
 	stamp = null;
 	flushTimer = null;
 	warnedBufferFull = false;
+	constructor(options) {
+		this.beforeSend = options?.beforeSend;
+	}
 	configure(stamp) {
 		if (this.stamp !== null && !isSameStamp(this.stamp, stamp)) this.flush();
 		this.stamp = stamp;
@@ -34,7 +38,12 @@ var AnalyticsClient = class {
 		};
 		if (options?.message !== void 0) event.message = options.message;
 		if (options?.properties !== void 0) event.properties = options.properties;
-		this.events.push(event);
+		if (options?.duration !== void 0) event.duration = options.duration;
+		if (options?.isError !== void 0) event.isError = options.isError;
+		if (options?.error !== void 0) event.error = options.error;
+		const outgoing = this.beforeSend ? this.beforeSend(event) : event;
+		if (outgoing === null) return;
+		this.events.push(outgoing);
 		if (this.events.length >= 50) {
 			this.flush();
 			return;
@@ -62,6 +71,88 @@ function isSameStamp(left, right) {
 	return left.distinctId === right.distinctId && left.sessionId === right.sessionId && left.ingestUrl === right.ingestUrl;
 }
 //#endregion
+//#region src/react/auto-capture.ts
+/**
+* Reserved auto-capture event names. The `$` prefix marks events emitted by the SDK itself
+* (lifecycle, errors, interactions) so the analytics UI can distinguish them from custom
+* `capture()` calls. Keep in sync with the server-side reserved namespace.
+*/
+const AUTO_EVENT = {
+	loaded: "$loaded",
+	visible: "$visible",
+	hidden: "$hidden",
+	closed: "$closed",
+	error: "$error"
+};
+/** Public DOM contract for declarative interaction capture: the attribute value is the event name. */
+const INTERACTION_ATTRIBUTE = "data-alpic-event";
+const INTERACTION_DATASET_KEY = "alpicEvent";
+const INTERACTION_DATASET_PREFIX = "alpic";
+/**
+* Resolves the nearest `[data-alpic-event]` ancestor of a click target into an event: the
+* attribute value is the name, and every other `data-alpic-*` attribute becomes a property.
+*/
+function resolveInteractionEvent(target) {
+	if (!(target instanceof Element)) return null;
+	const element = target.closest(`[${INTERACTION_ATTRIBUTE}]`);
+	if (element === null) return null;
+	const name = element.dataset[INTERACTION_DATASET_KEY];
+	if (name === void 0 || name === "") return null;
+	const properties = {};
+	for (const [key, value] of Object.entries(element.dataset)) {
+		if (key === INTERACTION_DATASET_KEY || !key.startsWith(INTERACTION_DATASET_PREFIX) || value === void 0) continue;
+		const unprefixed = key.slice(5);
+		const propertyKey = unprefixed.charAt(0).toLowerCase() + unprefixed.slice(1);
+		properties[propertyKey] = value;
+	}
+	return Object.keys(properties).length > 0 ? {
+		name,
+		properties
+	} : { name };
+}
+/** Captures uncaught errors and unhandled rejections as `$error`, mapped onto the ingest error columns. */
+function installErrorCapture(client) {
+	const onError = (event) => {
+		client.capture(AUTO_EVENT.error, {
+			isError: true,
+			error: event.message,
+			properties: {
+				stack: event.error instanceof Error ? event.error.stack : void 0,
+				source: event.filename
+			}
+		});
+	};
+	const onRejection = (event) => {
+		const reason = event.reason;
+		client.capture(AUTO_EVENT.error, {
+			isError: true,
+			error: reason instanceof Error ? reason.message : String(reason),
+			properties: {
+				stack: reason instanceof Error ? reason.stack : void 0,
+				source: "unhandledrejection"
+			}
+		});
+	};
+	window.addEventListener("error", onError);
+	window.addEventListener("unhandledrejection", onRejection);
+	return () => {
+		window.removeEventListener("error", onError);
+		window.removeEventListener("unhandledrejection", onRejection);
+	};
+}
+/** Captures clicks on `[data-alpic-event]` elements via a single delegated `document` listener. */
+function installInteractionCapture(client) {
+	const onClick = (event) => {
+		const resolved = resolveInteractionEvent(event.target);
+		if (resolved === null) return;
+		client.capture(resolved.name, resolved.properties ? { properties: resolved.properties } : void 0);
+	};
+	document.addEventListener("click", onClick);
+	return () => {
+		document.removeEventListener("click", onClick);
+	};
+}
+//#endregion
 //#region src/react/stamp.ts
 const ANALYTICS_META_KEY = "alpic/analytics";
 function parseAnalyticsStamp(metadata) {
@@ -131,24 +222,49 @@ const AnalyticsContext = createContext(null);
 * Wrap the widget once, then call `useAnalytics()` from components that capture events.
 * Events captured before configuration is available are buffered automatically.
 */
-function AlpicAnalytics({ children }) {
-	const [client] = useState(() => new AnalyticsClient());
+function AlpicAnalytics({ children, beforeSend, autoCapture }) {
+	const beforeSendRef = useRef(beforeSend);
+	beforeSendRef.current = beforeSend;
+	const [client] = useState(() => new AnalyticsClient({ beforeSend: (event) => {
+		const transform = beforeSendRef.current;
+		return transform ? transform(event) : event;
+	} }));
+	const lifecycle = autoCapture?.lifecycle ?? true;
+	const errors = autoCapture?.errors ?? true;
+	const interactions = autoCapture?.interactions ?? false;
 	useEffect(() => {
-		const unsubscribe = subscribeToAnalyticsStamp((stamp) => {
+		return subscribeToAnalyticsStamp((stamp) => {
 			client.configure(stamp);
 		});
-		const flushWhenHidden = () => {
-			if (document.visibilityState === "hidden") client.flush();
+	}, [client]);
+	useEffect(() => {
+		if (lifecycle) client.capture(AUTO_EVENT.loaded);
+		const onVisibilityChange = () => {
+			if (document.visibilityState === "hidden") {
+				if (lifecycle) client.capture(AUTO_EVENT.hidden);
+				client.flush();
+			} else if (lifecycle) client.capture(AUTO_EVENT.visible);
+		};
+		const onPageHide = () => {
+			if (lifecycle) client.capture(AUTO_EVENT.closed);
+			client.flush();
 		};
-		document.addEventListener("visibilitychange", flushWhenHidden);
-		window.addEventListener("pagehide", client.flush);
+		document.addEventListener("visibilitychange", onVisibilityChange);
+		window.addEventListener("pagehide", onPageHide);
 		return () => {
-			unsubscribe();
-			document.removeEventListener("visibilitychange", flushWhenHidden);
-			window.removeEventListener("pagehide", client.flush);
+			document.removeEventListener("visibilitychange", onVisibilityChange);
+			window.removeEventListener("pagehide", onPageHide);
 			client.flush();
 		};
-	}, [client]);
+	}, [client, lifecycle]);
+	useEffect(() => {
+		if (!errors) return;
+		return installErrorCapture(client);
+	}, [client, errors]);
+	useEffect(() => {
+		if (!interactions) return;
+		return installInteractionCapture(client);
+	}, [client, interactions]);
 	return /* @__PURE__ */ jsx(AnalyticsContext.Provider, {
 		value: client,
 		children
@@ -161,4 +277,4 @@ function useAnalytics() {
 	return analytics;
 }
 //#endregion
-export { AlpicAnalytics, useAnalytics };
+export { AUTO_EVENT, AlpicAnalytics, INTERACTION_ATTRIBUTE, useAnalytics };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpic-ai/insights",
-  "version": "1.156.0",
+  "version": "1.157.0",
   "description": "User insights middlewares for Alpic-hosted MCP servers",
   "type": "module",
   "main": "./dist/index.mjs",