@alpic-ai/insights 0.0.0-dev.g452a0bc → 0.0.0-dev.g45689c6

package/dist/index.d.mts

@@ -50,8 +50,8 @@ interface Analytics {
   /** Records a custom event on the current session's timeline, interleaved with tool calls. */
   capture(name: string, options?: CaptureOptions): void;
   /**
-   * Attaches traits to the current request's user (e.g. email, name, plan). The target user is
-   * resolved by Alpic from the request auth context — no id or sessionId is passed.
+   * Replaces the current request user's trait snapshot (e.g. email, name, plan). The target user
+   * is resolved by Alpic from the request auth context — no id or sessionId is passed.
    */
   identify(traits: Record<string, string>): void;
 }
@@ -62,13 +62,26 @@ interface Analytics {
 interface AnalyticsExtra {
   analytics: Analytics;
 }
+interface AnalyticsEvent extends CaptureOptions {
+  name: string;
+  timestamp: number;
+}
+interface AnalyticsBatch {
+  events: AnalyticsEvent[];
+  traits?: Record<string, string>;
+}
+interface AnalyticsMiddlewareOptions {
+  /** Receives each request's analytics locally, whether or not the server is hosted by Alpic. */
+  handler?: (batch: AnalyticsBatch) => Promise<void> | void;
+}
 /**
  * Lets MCP server builders record custom analytics events and user traits from inside tool
  * handlers, via `extra.analytics.capture(...)` / `extra.analytics.identify(...)`. Calls are
- * buffered during the request and flushed into the response `_meta`, where the Alpic proxy
- * ingests and strips them before the result reaches the client.
+ * buffered during the request. On Alpic, private environment-provided `_meta` keys carry them to
+ * the proxy for ingestion. Locally, pass a handler to receive them without exposing analytics in
+ * the MCP response.
  */
-declare function analyticsMiddleware(): McpMiddlewareFn;
+declare function analyticsMiddleware(options?: AnalyticsMiddlewareOptions): McpMiddlewareFn;
 //#endregion
 //#region src/feedback-middleware.d.ts
 interface FeedbackData {
@@ -116,7 +129,8 @@ declare const captureIntents: (server: McpServer | Server, options?: IntentMiddl
  * Enables custom analytics events on a vanilla `@modelcontextprotocol/sdk` server. Accepts the
  * high-level `McpServer` or the low-level `Server` and patches the `tools/call` request handlers
  * so tool handlers can call `extra.analytics.capture(...)` / `extra.analytics.identify(...)`.
+ * Pass a handler in `options` to receive analytics when running outside Alpic.
  */
-declare const track: (server: McpServer | Server) => void;
+declare const track: (server: McpServer | Server, options?: AnalyticsMiddlewareOptions) => void;
 //#endregion
-export { type Analytics, type AnalyticsExtra, type CaptureOptions, type FeedbackData, type FeedbackMiddlewareOptions, type IntentMiddlewareOptions, type McpMiddlewareFn, type PromptData, analyticsMiddleware, captureFeedback, captureIntents, feedbackMiddleware, intentMiddleware, track };
+export { type Analytics, type AnalyticsBatch, type AnalyticsEvent, type AnalyticsExtra, type AnalyticsMiddlewareOptions, type CaptureOptions, type FeedbackData, type FeedbackMiddlewareOptions, type IntentMiddlewareOptions, type McpMiddlewareFn, type PromptData, analyticsMiddleware, captureFeedback, captureIntents, feedbackMiddleware, intentMiddleware, track };

package/dist/index.mjs

@@ -1,7 +1,5 @@
 import { CallToolRequestSchema, CallToolResultSchema, ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
 //#region src/analytics-middleware.ts
-const ALPIC_EVENTS_META_KEY = "alpic/events";
-const ALPIC_IDENTIFY_META_KEY = "alpic/identify";
 const MAX_EVENTS_PER_REQUEST = 50;
 function warnInDev(message) {
 	if (process.env.NODE_ENV !== "production") console.warn(`[insights] ${message}`);
@@ -32,10 +30,7 @@ function createAnalyticsBuffer() {
 					warnInDev("analytics.identify() was called after the request settled; the traits were dropped. Identify before the tool handler returns.");
 					return;
 				}
-				traits = {
-					...traits,
-					...newTraits
-				};
+				traits = { ...newTraits };
 			}
 		},
 		settle: () => {
@@ -52,10 +47,11 @@ function createAnalyticsBuffer() {
 /**
 * Lets MCP server builders record custom analytics events and user traits from inside tool
 * handlers, via `extra.analytics.capture(...)` / `extra.analytics.identify(...)`. Calls are
-* buffered during the request and flushed into the response `_meta`, where the Alpic proxy
-* ingests and strips them before the result reaches the client.
+* buffered during the request. On Alpic, private environment-provided `_meta` keys carry them to
+* the proxy for ingestion. Locally, pass a handler to receive them without exposing analytics in
+* the MCP response.
 */
-function analyticsMiddleware() {
+function analyticsMiddleware(options) {
 	return async (request, extra, next) => {
 		if (request.method !== "tools/call" || extra === null || typeof extra !== "object") return next();
 		const buffer = createAnalyticsBuffer();
@@ -67,11 +63,23 @@ function analyticsMiddleware() {
 			buffer.settle();
 		}
 		if (buffer.events.length === 0 && buffer.traits === void 0) return rawResult;
+		const batch = {
+			events: [...buffer.events],
+			...buffer.traits === void 0 ? {} : { traits: { ...buffer.traits } }
+		};
+		if (options?.handler) try {
+			await options.handler(batch);
+		} catch (error) {
+			console.error("Error calling analytics handler", error);
+		}
+		const eventsMetaKey = process.env.ALPIC_EVENTS_META_KEY || void 0;
+		const identifyMetaKey = process.env.ALPIC_IDENTIFY_META_KEY || void 0;
+		if (eventsMetaKey === void 0 && identifyMetaKey === void 0) return rawResult;
 		if (!CallToolResultSchema.safeParse(rawResult).success) return rawResult;
 		const result = rawResult;
 		const meta = { ...result._meta };
-		if (buffer.events.length > 0) meta[ALPIC_EVENTS_META_KEY] = buffer.events;
-		if (buffer.traits !== void 0) meta[ALPIC_IDENTIFY_META_KEY] = buffer.traits;
+		if (eventsMetaKey !== void 0 && buffer.events.length > 0) meta[eventsMetaKey] = buffer.events;
+		if (identifyMetaKey !== void 0 && buffer.traits !== void 0) meta[identifyMetaKey] = buffer.traits;
 		return {
 			...result,
 			_meta: meta
@@ -254,41 +262,17 @@ function intentMiddleware(options) {
 					...tool.inputSchema.properties,
 					[USER_INTENT_FIELD]: {
 						type: "string",
-						description: `A concise summary of what the user is trying to accomplish, derived from their message or the
-conversation context that triggered this tool call.
-This is used to understand the user's intent and context to improve the overall user experience.
-
-- For short, self-contained prompts (e.g. "I want new shoes"), copy the user message as-is.
-- For longer conversations or detailed requests, summarize the core goal and any relevant
-  context in 1-2 sentences. Focus on intent, constraints, and preferences - not the full
-  dialogue.
-
-Before sending, strip all personally identifiable information (PII), including but not
-limited to:
-  - Names (first, last, usernames, handles)
-  - Email addresses
-  - Phone numbers
-  - Physical addresses (street, city, zip/postal code, country when tied to an individual)
-  - Dates of birth or exact ages
-  - Government-issued ID numbers (SSN, passport, driver's license, etc.)
-  - Payment or financial information (card numbers, bank accounts, etc.)
-  - IP addresses or device identifiers
-  - Account credentials (passwords, tokens, API keys)
-  - Health or biometric data
-  - Any other information that could identify a specific individual
-
-Replace stripped values with a generic placeholder (e.g. "[name]", "[email]", "[address]").
+						description: `A concise, natural-language summary of what the user is trying to accomplish, derived from the conversation that triggered this tool call. Base it on the user's own words.
 
-Examples:
-  User: "I want red running shoes under $100"
-  -> "I want red running shoes under $100"
+This is context that helps understand the user's request and improve the tool's response; it does not trigger any destructive action.
 
-  User: "Hi, I'm John Smith, john@example.com, and I'm looking for flights from Paris to
-         Tokyo for 2 adults departing around mid-June, budget around EUR2000 total"
-  -> "Looking for flights from Paris to Tokyo for 2 adults, mid-June, budget ~EUR2000"
+Before sending, strip all personally identifiable information (names, emails, phone numbers, addresses, dates of birth, ID numbers, payment details, credentials, IP addresses, and device identifiers) and sensitive personal data (such as health, religion, or precise location).
 
-  User: "I need help resetting my password for account ID acct_12345"
-  -> "I need help resetting my password for account ID [account_id]"`
+- Short, self-contained request: copy it as-is.
+  "I want new shoes" -> "I want new shoes"
+- Longer conversation: summarize the core goal, constraints, and preferences in 1-2 sentences.
+  "Hi, I'm Jane (jane@mail.com), I'd love a gift under EUR1000 for my mum's birthday"
+  -> "looking for a gift under EUR1000 for my mum's birthday"`
 					}
 				};
 			}
@@ -356,10 +340,11 @@ const captureIntents = (server, options) => {
 * Enables custom analytics events on a vanilla `@modelcontextprotocol/sdk` server. Accepts the
 * high-level `McpServer` or the low-level `Server` and patches the `tools/call` request handlers
 * so tool handlers can call `extra.analytics.capture(...)` / `extra.analytics.identify(...)`.
+* Pass a handler in `options` to receive analytics when running outside Alpic.
 */
-const track = (server) => {
+const track = (server, options) => {
 	installCaptureMiddleware(server, {
-		middleware: analyticsMiddleware(),
+		middleware: analyticsMiddleware(options),
 		installedMarker: "__alpicTrackInstalled",
 		disabledWarning: "Analytics capture disabled."
 	});

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,54 @@ 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);
+		let closed = false;
+		const onVisibilityChange = () => {
+			if (document.visibilityState === "hidden") {
+				if (lifecycle && !closed) client.capture(AUTO_EVENT.hidden);
+				client.flush();
+			} else {
+				closed = false;
+				if (lifecycle) client.capture(AUTO_EVENT.visible);
+			}
+		};
+		const onPageHide = () => {
+			if (lifecycle) client.capture(AUTO_EVENT.closed);
+			closed = true;
+			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 +282,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": "0.0.0-dev.g452a0bc",
+  "version": "0.0.0-dev.g45689c6",
   "description": "User insights middlewares for Alpic-hosted MCP servers",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -41,11 +41,11 @@
     "@types/node": "^25.9.5",
     "@types/react": "19.2.17",
     "jsdom": "^29.1.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "shx": "^0.4.0",
-    "skybridge": "^1.2.7",
-    "tsdown": "^0.22.5",
+    "skybridge": "^1.3.0",
+    "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3"