@alpic-ai/insights 0.0.0-dev.g2a45f1b → 0.0.0-dev.g2a6be45

package/dist/index.d.mts

@@ -36,6 +36,40 @@ type McpMiddlewareFn = (request: {
  */
 declare function intentMiddleware(options?: IntentMiddlewareOptions): McpMiddlewareFn;
 //#endregion
+//#region src/analytics-middleware.d.ts
+interface CaptureOptions {
+  message?: string;
+  /** Duration of the operation the event describes, in milliseconds. */
+  duration?: number;
+  isError?: boolean;
+  error?: string;
+  /** Freeform event detail. Not indexed — filtering on a property key is a query-time scan. */
+  properties?: Record<string, unknown>;
+}
+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.
+   */
+  identify(traits: Record<string, string>): void;
+}
+/**
+ * Shape of the handler `extra` once `analyticsMiddleware()` (or `track(server)`) is installed.
+ * Cast the handler's `extra` to this to access `analytics` with types.
+ */
+interface AnalyticsExtra {
+  analytics: Analytics;
+}
+/**
+ * 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.
+ */
+declare function analyticsMiddleware(): McpMiddlewareFn;
+//#endregion
 //#region src/feedback-middleware.d.ts
 interface FeedbackData {
   content: string;
@@ -77,4 +111,12 @@ declare const captureFeedback: (server: McpServer | Server, options?: FeedbackMi
  */
 declare const captureIntents: (server: McpServer | Server, options?: IntentMiddlewareOptions) => void;
 //#endregion
-export { type FeedbackData, type FeedbackMiddlewareOptions, type IntentMiddlewareOptions, type McpMiddlewareFn, type PromptData, captureFeedback, captureIntents, feedbackMiddleware, intentMiddleware };
+//#region src/track.d.ts
+/**
+ * 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(...)`.
+ */
+declare const track: (server: McpServer | Server) => 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 };

package/dist/index.mjs

@@ -1,4 +1,84 @@
 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}`);
+}
+function createAnalyticsBuffer() {
+	const events = [];
+	let traits;
+	let settled = false;
+	return {
+		analytics: {
+			capture(name, options) {
+				if (settled) {
+					warnInDev(`analytics.capture("${name}") was called after the request settled; the event was dropped. Capture events before the tool handler returns.`);
+					return;
+				}
+				if (events.length >= MAX_EVENTS_PER_REQUEST) {
+					warnInDev(`analytics.capture("${name}") exceeded the ${MAX_EVENTS_PER_REQUEST} events per request limit; the event was dropped.`);
+					return;
+				}
+				events.push({
+					...options,
+					name,
+					timestamp: Date.now()
+				});
+			},
+			identify(newTraits) {
+				if (settled) {
+					warnInDev("analytics.identify() was called after the request settled; the traits were dropped. Identify before the tool handler returns.");
+					return;
+				}
+				traits = {
+					...traits,
+					...newTraits
+				};
+			}
+		},
+		settle: () => {
+			settled = true;
+		},
+		get events() {
+			return events;
+		},
+		get traits() {
+			return traits;
+		}
+	};
+}
+/**
+* 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.
+*/
+function analyticsMiddleware() {
+	return async (request, extra, next) => {
+		if (request.method !== "tools/call" || extra === null || typeof extra !== "object") return next();
+		const buffer = createAnalyticsBuffer();
+		extra.analytics = buffer.analytics;
+		let rawResult;
+		try {
+			rawResult = await next();
+		} finally {
+			buffer.settle();
+		}
+		if (buffer.events.length === 0 && buffer.traits === 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;
+		return {
+			...result,
+			_meta: meta
+		};
+	};
+}
+//#endregion
 //#region src/feedback-middleware.ts
 const FEEDBACK_TOOL_NAME = "send_feedback";
 const FEEDBACK_TOOL_DESCRIPTION = "Send feedback about this MCP server to its operators. Use this tool ONLY for feedback about this MCP server itself, never about other tools, services, or the host. You MAY call this tool when you detect a genuine issue with this server (e.g. a tool that failed unexpectedly, an unhelpful response, a missing capability). You MAY also call it when the user explicitly asks to send feedback. Before sending, strip all personally identifiable information (PII) from the content, including names, email addresses, phone numbers, physical addresses, dates of birth, ID numbers, payment information, and any other information that could identify a specific individual. Replace stripped values with generic placeholders (e.g. \"[name]\", \"[email]\").";
@@ -271,4 +351,18 @@ const captureIntents = (server, options) => {
 	});
 };
 //#endregion
-export { captureFeedback, captureIntents, feedbackMiddleware, intentMiddleware };
+//#region src/track.ts
+/**
+* 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(...)`.
+*/
+const track = (server) => {
+	installCaptureMiddleware(server, {
+		middleware: analyticsMiddleware(),
+		installedMarker: "__alpicTrackInstalled",
+		disabledWarning: "Analytics capture disabled."
+	});
+};
+//#endregion
+export { analyticsMiddleware, captureFeedback, captureIntents, feedbackMiddleware, intentMiddleware, track };

package/dist/react/index.d.mts

@@ -0,0 +1,24 @@
+import { ReactNode } from "react";
+//#region src/react/analytics-client.d.ts
+interface CaptureOptions {
+  message?: string;
+  properties?: Record<string, unknown>;
+}
+//#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;
+}
+/**
+ * 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;
+/** Returns the analytics client from the nearest `AlpicAnalytics` provider. */
+declare function useAnalytics(): Analytics;
+//#endregion
+export { AlpicAnalytics, type Analytics, type CaptureOptions, useAnalytics };

package/dist/react/index.mjs

@@ -0,0 +1,164 @@
+import { createContext, useContext, useEffect, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react/analytics-transport.ts
+function postAnalyticsBatch(ingestUrl, events) {
+	return fetch(ingestUrl, {
+		method: "POST",
+		keepalive: true,
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ events })
+	}).then(() => void 0, () => void 0);
+}
+const FLUSH_DELAY_MS = 2e3;
+var AnalyticsClient = class {
+	events = [];
+	stamp = null;
+	flushTimer = null;
+	warnedBufferFull = false;
+	configure(stamp) {
+		if (this.stamp !== null && !isSameStamp(this.stamp, stamp)) this.flush();
+		this.stamp = stamp;
+		if (this.events.length > 0) this.scheduleFlush();
+	}
+	capture = (name, options) => {
+		if (this.events.length >= 100) {
+			if (!this.warnedBufferFull) {
+				console.warn("[@alpic-ai/insights] analytics buffer is full, dropping events");
+				this.warnedBufferFull = true;
+			}
+			return;
+		}
+		const event = {
+			name,
+			timestamp: Date.now()
+		};
+		if (options?.message !== void 0) event.message = options.message;
+		if (options?.properties !== void 0) event.properties = options.properties;
+		this.events.push(event);
+		if (this.events.length >= 50) {
+			this.flush();
+			return;
+		}
+		this.scheduleFlush();
+	};
+	flush = () => {
+		if (this.flushTimer !== null) {
+			clearTimeout(this.flushTimer);
+			this.flushTimer = null;
+		}
+		if (this.stamp === null) return;
+		while (this.events.length > 0) {
+			const batch = this.events.splice(0, 50);
+			postAnalyticsBatch(this.stamp.ingestUrl, batch);
+		}
+		this.warnedBufferFull = false;
+	};
+	scheduleFlush() {
+		if (this.stamp === null || this.flushTimer !== null) return;
+		this.flushTimer = setTimeout(this.flush, FLUSH_DELAY_MS);
+	}
+};
+function isSameStamp(left, right) {
+	return left.distinctId === right.distinctId && left.sessionId === right.sessionId && left.ingestUrl === right.ingestUrl;
+}
+//#endregion
+//#region src/react/stamp.ts
+const ANALYTICS_META_KEY = "alpic/analytics";
+function parseAnalyticsStamp(metadata) {
+	if (metadata === null || typeof metadata !== "object") return null;
+	const candidate = metadata[ANALYTICS_META_KEY];
+	if (candidate === null || candidate === void 0 || typeof candidate !== "object") return null;
+	const { distinctId, sessionId, ingestUrl } = candidate;
+	if (typeof distinctId !== "string" || typeof sessionId !== "string" || typeof ingestUrl !== "string") return null;
+	return {
+		distinctId,
+		sessionId,
+		ingestUrl
+	};
+}
+//#endregion
+//#region src/react/stamp-source.ts
+const TOOL_RESULT_METHOD = "ui/notifications/tool-result";
+const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
+const subscribers = /* @__PURE__ */ new Set();
+let latestProtocolStamp = null;
+let isObservingRuntime = false;
+function subscribeToAnalyticsStamp(onStamp) {
+	observeRuntime();
+	subscribers.add(onStamp);
+	if (latestProtocolStamp !== null) onStamp(latestProtocolStamp);
+	else emitOpenAiStamp(onStamp);
+	return () => {
+		subscribers.delete(onStamp);
+	};
+}
+function observeRuntime() {
+	if (isObservingRuntime || typeof window === "undefined") return;
+	window.addEventListener("message", handleToolResultMessage);
+	window.addEventListener(SET_GLOBALS_EVENT_TYPE, handleOpenAiGlobals, { passive: true });
+	isObservingRuntime = true;
+}
+function handleToolResultMessage(event) {
+	if (event.source !== window.parent || event.data === null || typeof event.data !== "object") return;
+	const message = event.data;
+	if (message.jsonrpc !== "2.0" || message.method !== TOOL_RESULT_METHOD) return;
+	const params = message.params;
+	if (params === null || typeof params !== "object") return;
+	const stamp = parseAnalyticsStamp(params._meta);
+	if (stamp === null) return;
+	latestProtocolStamp = stamp;
+	for (const subscriber of subscribers) subscriber(stamp);
+}
+function handleOpenAiGlobals() {
+	if (latestProtocolStamp !== null) return;
+	const globals = window;
+	if (globals.openai === void 0) return;
+	const stamp = parseAnalyticsStamp(globals.openai.toolResponseMetadata);
+	if (stamp === null) return;
+	for (const subscriber of subscribers) subscriber(stamp);
+}
+function emitOpenAiStamp(onStamp) {
+	if (typeof window === "undefined") return;
+	const stamp = parseAnalyticsStamp(window.openai?.toolResponseMetadata);
+	if (stamp !== null) onStamp(stamp);
+}
+observeRuntime();
+//#endregion
+//#region src/react/alpic-analytics.tsx
+const AnalyticsContext = createContext(null);
+/**
+* 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.
+*/
+function AlpicAnalytics({ children }) {
+	const [client] = useState(() => new AnalyticsClient());
+	useEffect(() => {
+		const unsubscribe = subscribeToAnalyticsStamp((stamp) => {
+			client.configure(stamp);
+		});
+		const flushWhenHidden = () => {
+			if (document.visibilityState === "hidden") client.flush();
+		};
+		document.addEventListener("visibilitychange", flushWhenHidden);
+		window.addEventListener("pagehide", client.flush);
+		return () => {
+			unsubscribe();
+			document.removeEventListener("visibilitychange", flushWhenHidden);
+			window.removeEventListener("pagehide", client.flush);
+			client.flush();
+		};
+	}, [client]);
+	return /* @__PURE__ */ jsx(AnalyticsContext.Provider, {
+		value: client,
+		children
+	});
+}
+/** Returns the analytics client from the nearest `AlpicAnalytics` provider. */
+function useAnalytics() {
+	const analytics = useContext(AnalyticsContext);
+	if (analytics === null) throw new Error("useAnalytics must be used within an <AlpicAnalytics> provider");
+	return analytics;
+}
+//#endregion
+export { AlpicAnalytics, useAnalytics };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpic-ai/insights",
-  "version": "0.0.0-dev.g2a45f1b",
+  "version": "0.0.0-dev.g2a6be45",
   "description": "User insights middlewares for Alpic-hosted MCP servers",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -9,6 +9,10 @@
     ".": {
       "types": "./dist/index.d.mts",
       "default": "./dist/index.mjs"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.mts",
+      "default": "./dist/react/index.mjs"
     }
   },
   "files": [
@@ -18,17 +22,27 @@
   "license": "ISC",
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.29.0 <2",
+    "react": ">=18.0.0",
     "skybridge": "^0.36.3 || ^1.0.0"
   },
   "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
     "skybridge": {
       "optional": true
     }
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@total-typescript/tsconfig": "^1.0.4",
     "@types/node": "^25.9.5",
+    "@types/react": "19.2.17",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "shx": "^0.4.0",
     "skybridge": "^1.2.7",
     "tsdown": "^0.22.9",