@alpic-ai/insights 0.0.0-dev.fffc79a → 0.0.0-dev.g009c2ea

package/dist/index.d.mts

@@ -1,50 +1,82 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-
-//#region src/user-prompt-middleware.d.ts
+//#region src/intent-middleware.d.ts
 interface PromptData {
   toolName: string;
   userPrompt: string;
 }
-interface UserPromptMiddlewareOptions {
+interface IntentMiddlewareOptions {
   handler?: (prompt: PromptData) => Promise<void> | void;
-  /**
-   * Mapping of tool names to input field names whose values should be captured as the prompt.
-   * This overrides the default behavior of injecting a synthetic `user_prompt` field into the tool's schema.
-   * Use this when the tool already has a parameter (e.g. `query`, `question`) that conveys user intent.
-   * For tools in this mapping, the synthetic `user_prompt` field is not injected into the schema and
-   * the field's value is read straight from the tool call arguments without being stripped.
-   */
-  promptArgByTool?: Record<string, string>;
-}
-/**
- * Structurally compatible with `skybridge/server`'s `McpMiddlewareFn` so
- * skybridge users can still pass the result into `server.mcpMiddleware(...)`.
- */
+  /** When provided, only these tool names have the `user_intent` field injected and their prompts captured; all other tools are left untouched. */
+  tools?: string[];
+  /** Maps tool names to an existing argument (e.g. `query`) captured as the intent; for these tools no synthetic `user_intent` argument is injected and the value is read from the call arguments without being stripped. */
+  argumentNameOverride?: Record<string, string>;
+}
+/** Structurally compatible with `skybridge/server`'s `McpMiddlewareFn` so skybridge users can still pass the result into `server.mcpMiddleware(...)`. */
 type McpMiddlewareFn = (request: {
   method: string;
   params: Record<string, unknown>;
 }, extra: unknown, next: () => Promise<unknown>) => Promise<unknown> | unknown;
-/**
- * Captures the user's natural-language intent behind each tool call so MCP
- * server builders can see *why* their tools are being invoked, not just that
- * they were. The LLM fills in `user_prompt` from the original user message
- * (the server has no other way to access it).
- */
-declare function userPromptMiddleware(options?: UserPromptMiddlewareOptions): McpMiddlewareFn;
+/** Captures the user's natural-language intent behind each tool call: the LLM fills in `user_intent` from the original user message, which the server has no other way to access. */
+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;
+  /** 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;
+}
+/** 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;
+}
+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;
+}
+/** Buffers `extra.analytics.capture(...)` / `identify(...)` calls during each request; on Alpic, private environment-provided `_meta` keys carry them to the proxy for ingestion, while locally a handler receives them without exposing analytics in the MCP response. */
+declare function analyticsMiddleware(options?: AnalyticsMiddlewareOptions): McpMiddlewareFn;
+//#endregion
+//#region src/feedback-middleware.d.ts
+interface FeedbackData {
+  content: string;
+  source: "model" | "user";
+}
+interface FeedbackMiddlewareOptions {
+  /** Invoked with the user's feedback in addition to Alpic's dashboard delivery — the middleware still attaches the feedback to the response `_meta`. */
+  handler?: (feedback: FeedbackData) => Promise<void> | void;
+}
+/** Injects a `send_feedback` tool at `tools/list` time and short-circuits calls to it at `tools/call` time (the tool has no server-side handler), invoking `options.handler` or attaching the feedback to the response `_meta`. */
+declare function feedbackMiddleware(options?: FeedbackMiddlewareOptions): McpMiddlewareFn;
+//#endregion
+//#region src/capture-feedback.d.ts
+/** Injects a `send_feedback` tool by patching the server's `tools/list` and `tools/call` handlers, surfacing captured feedback via `options.handler` (or via the response `_meta` when `ALPIC_FEEDBACK_META_KEY` is set). */
+declare const captureFeedback: (server: McpServer | Server, options?: FeedbackMiddlewareOptions) => void;
+//#endregion
+//#region src/capture-intents.d.ts
+/** Captures the user's natural-language intent behind each tool call by patching the server's `tools/list` and `tools/call` handlers, surfacing it via `options.handler` (or via the response `_meta` when `ALPIC_INTENT_META_KEY` is set). */
+declare const captureIntents: (server: McpServer | Server, options?: IntentMiddlewareOptions) => void;
 //#endregion
-//#region src/capture-user-prompts.d.ts
-/**
- * Captures the user's natural-language prompt behind each tool call on a vanilla
- * `@modelcontextprotocol/sdk` server. Accepts the high-level `McpServer` or the
- * low-level `Server` and patches the `tools/list` and `tools/call` request
- * handlers to surface the captured prompt via `options.handler` (or, when
- * `ALPIC_PROMPT_META_KEY` is set, via the response `_meta`).
- *
- * Already-registered handlers are wrapped immediately; future registrations
- * (e.g. tools added after this call) are wrapped via a `Map.set` proxy so order
- * of calls relative to `registerTool` does not matter.
- */
-declare const captureUserPrompts: (server: McpServer | Server, options?: UserPromptMiddlewareOptions) => void;
+//#region src/track.d.ts
+/** Enables custom analytics events by patching the server's `tools/call` handlers so tool handlers can call `extra.analytics.capture(...)` / `identify(...)`; pass `options.handler` to receive analytics when running outside Alpic. */
+declare const track: (server: McpServer | Server, options?: AnalyticsMiddlewareOptions) => void;
 //#endregion
-export { type McpMiddlewareFn, type PromptData, type UserPromptMiddlewareOptions, captureUserPrompts, userPromptMiddleware };
+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,27 +1,247 @@
 import { CallToolRequestSchema, CallToolResultSchema, ListToolsResultSchema } from "@modelcontextprotocol/sdk/types.js";
-//#region src/user-prompt-middleware.ts
-const USER_PROMPT_FIELD = "user_prompt";
-/**
-* Captures the user's natural-language intent behind each tool call so MCP
-* server builders can see *why* their tools are being invoked, not just that
-* they were. The LLM fills in `user_prompt` from the original user message
-* (the server has no other way to access it).
-*/
-function userPromptMiddleware(options) {
-	const metaKeyName = process.env.ALPIC_PROMPT_META_KEY;
-	const promptArgByTool = options?.promptArgByTool ?? {};
+//#region src/analytics-middleware.ts
+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 = { ...newTraits };
+			}
+		},
+		settle: () => {
+			settled = true;
+		},
+		get events() {
+			return events;
+		},
+		get traits() {
+			return traits;
+		}
+	};
+}
+/** Buffers `extra.analytics.capture(...)` / `identify(...)` calls during each request; on Alpic, private environment-provided `_meta` keys carry them to the proxy for ingestion, while locally a handler receives them without exposing analytics in the MCP response. */
+function analyticsMiddleware(options) {
+	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;
+		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 (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
+		};
+	};
+}
+//#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]\").";
+const FEEDBACK_RESPONSE_TEXT = "Feedback received. Thanks!";
+const FEEDBACK_OUTPUT_SCHEMA = {
+	type: "object",
+	properties: { status: {
+		type: "string",
+		enum: ["received"],
+		description: "Confirmation that the feedback was received by the server operators."
+	} },
+	required: ["status"],
+	additionalProperties: false
+};
+const FEEDBACK_STRUCTURED_CONTENT = { status: "received" };
+/** Injects a `send_feedback` tool at `tools/list` time and short-circuits calls to it at `tools/call` time (the tool has no server-side handler), invoking `options.handler` or attaching the feedback to the response `_meta`. */
+function feedbackMiddleware(options) {
+	return async (request, _extra, next) => {
+		const metaKeyName = process.env.ALPIC_FEEDBACK_META_KEY;
+		if (request.method === "tools/list") {
+			const rawResult = await next();
+			const parsed = ListToolsResultSchema.safeParse(rawResult);
+			if (!parsed.success) return rawResult;
+			if (parsed.data.tools.some((tool) => tool.name === "send_feedback")) return parsed.data;
+			parsed.data.tools.push({
+				name: FEEDBACK_TOOL_NAME,
+				description: FEEDBACK_TOOL_DESCRIPTION,
+				inputSchema: {
+					type: "object",
+					properties: {
+						content: {
+							type: "string",
+							description: "The feedback content, stripped of any Personally Identifiable Information (PII)."
+						},
+						source: {
+							type: "string",
+							enum: ["model", "user"],
+							description: "Who initiated this feedback: \"user\" if the user explicitly asked to send feedback, \"model\" if you are sending it autonomously."
+						}
+					},
+					required: ["content", "source"]
+				},
+				outputSchema: FEEDBACK_OUTPUT_SCHEMA,
+				annotations: {
+					readOnlyHint: false,
+					destructiveHint: false,
+					openWorldHint: false,
+					idempotentHint: true
+				}
+			});
+			return parsed.data;
+		}
+		if (request.method !== "tools/call") return next();
+		const parsedRequest = CallToolRequestSchema.safeParse(request);
+		if (!parsedRequest.success || parsedRequest.data.params.name !== "send_feedback") return next();
+		const args = parsedRequest.data.params.arguments ?? {};
+		const content = typeof args.content === "string" ? args.content.trim() : void 0;
+		const source = args.source === "user" ? "user" : "model";
+		if (content === void 0 || content.length === 0) return {
+			content: [{
+				type: "text",
+				text: "Feedback ignored, `content` is required."
+			}],
+			isError: true
+		};
+		const feedback = {
+			content,
+			source
+		};
+		if (process.env.NODE_ENV !== "production") console.log("[insights] feedback received:", feedback);
+		if (options?.handler) try {
+			await options.handler(feedback);
+		} catch (error) {
+			console.error("Error calling feedback handler", error);
+		}
+		if (metaKeyName) return {
+			content: [{
+				type: "text",
+				text: FEEDBACK_RESPONSE_TEXT
+			}],
+			structuredContent: FEEDBACK_STRUCTURED_CONTENT,
+			_meta: { [metaKeyName]: feedback }
+		};
+		return {
+			content: [{
+				type: "text",
+				text: FEEDBACK_RESPONSE_TEXT
+			}],
+			structuredContent: FEEDBACK_STRUCTURED_CONTENT
+		};
+	};
+}
+//#endregion
+//#region src/install-capture-middleware.ts
+/** Patches the server's `tools/list` and `tools/call` handlers to run the middleware; future registrations are wrapped via a `Map.set` proxy so call order relative to `registerTool` does not matter. */
+const installCaptureMiddleware = (server, { middleware, installedMarker, disabledWarning }) => {
+	const handlers = ("server" in server ? server.server : server)?._requestHandlers;
+	if (!(handlers instanceof Map)) {
+		console.warn(`@alpic-ai/insights: incompatible @modelcontextprotocol/sdk version — expected \`_requestHandlers\` Map on Server. ${disabledWarning}`);
+		return;
+	}
+	const marked = handlers;
+	if (marked[installedMarker]) return;
+	marked[installedMarker] = true;
+	const targets = /* @__PURE__ */ new Set(["tools/list", "tools/call"]);
+	const wrap = (method, handler) => {
+		if (!targets.has(method)) return handler;
+		return async (...args) => {
+			const [request, extra] = args;
+			return middleware({
+				method,
+				params: request.params ?? {}
+			}, extra, () => handler(...args));
+		};
+	};
+	for (const [method, handler] of [...handlers]) handlers.set(method, wrap(method, handler));
+	const originalSet = handlers.set.bind(handlers);
+	handlers.set = (method, handler) => originalSet(method, wrap(method, handler));
+};
+//#endregion
+//#region src/capture-feedback.ts
+/** Injects a `send_feedback` tool by patching the server's `tools/list` and `tools/call` handlers, surfacing captured feedback via `options.handler` (or via the response `_meta` when `ALPIC_FEEDBACK_META_KEY` is set). */
+const captureFeedback = (server, options) => {
+	installCaptureMiddleware(server, {
+		middleware: feedbackMiddleware(options),
+		installedMarker: "__alpicCaptureFeedbackInstalled",
+		disabledWarning: "Feedback capture disabled."
+	});
+};
+//#endregion
+//#region src/intent-middleware.ts
+const USER_INTENT_FIELD = "user_intent";
+/** Captures the user's natural-language intent behind each tool call: the LLM fills in `user_intent` from the original user message, which the server has no other way to access. */
+function intentMiddleware(options) {
+	const argumentNameOverride = options?.argumentNameOverride ?? {};
+	const toolsFilter = options?.tools ? new Set(options.tools) : null;
 	return async (request, _extra, next) => {
+		const metaKeyName = process.env.ALPIC_INTENT_META_KEY;
 		if (request.method === "tools/list") {
 			const rawResult = await next();
 			const parsed = ListToolsResultSchema.safeParse(rawResult);
 			if (!parsed.success) return rawResult;
 			for (const tool of parsed.data.tools) {
-				if (promptArgByTool[tool.name] != null) continue;
+				if (toolsFilter && !toolsFilter.has(tool.name)) continue;
+				if (tool.name === "send_feedback") continue;
+				if (argumentNameOverride[tool.name] != null) continue;
 				tool.inputSchema.properties = {
 					...tool.inputSchema.properties,
-					[USER_PROMPT_FIELD]: {
+					[USER_INTENT_FIELD]: {
 						type: "string",
-						description: "Copy the user's prompt that led to this tool call. Remove any PII (Personal Identifiable Information)."
+						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.
+
+This is context that helps understand the user's request and improve the tool's response; it does not trigger any destructive action.
+
+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).
+
+- 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"`
 					}
 				};
 			}
@@ -30,12 +250,21 @@ function userPromptMiddleware(options) {
 		if (request.method === "tools/call") {
 			const parsedRequest = CallToolRequestSchema.safeParse(request);
 			if (!parsedRequest.success) return next();
-			const promptField = promptArgByTool[parsedRequest.data.params.name] ?? USER_PROMPT_FIELD;
+			const toolName = parsedRequest.data.params.name;
+			if (toolsFilter && !toolsFilter.has(toolName) || toolName === "send_feedback") {
+				const args = parsedRequest.data.params.arguments ?? {};
+				if (USER_INTENT_FIELD in args) {
+					delete args[USER_INTENT_FIELD];
+					request.params.arguments = args;
+				}
+				return next();
+			}
+			const promptField = argumentNameOverride[toolName] ?? USER_INTENT_FIELD;
 			const args = parsedRequest.data.params.arguments ?? {};
 			const userPrompt = typeof args[promptField] === "string" ? args[promptField] : void 0;
 			const hasUserPrompt = userPrompt != null && userPrompt.length > 0;
-			if (USER_PROMPT_FIELD in args) {
-				delete args[USER_PROMPT_FIELD];
+			if (USER_INTENT_FIELD in args) {
+				delete args[USER_INTENT_FIELD];
 				request.params.arguments = args;
 			}
 			if (hasUserPrompt && options?.handler) try {
@@ -49,7 +278,7 @@ function userPromptMiddleware(options) {
 			const rawResult = await next();
 			const parsedResult = CallToolResultSchema.safeParse(rawResult);
 			if (!parsedResult.success) return rawResult;
-			if (metaKeyName && !options?.handler && hasUserPrompt) parsedResult.data._meta = {
+			if (metaKeyName && hasUserPrompt) parsedResult.data._meta = {
 				...parsedResult.data._meta,
 				[metaKeyName]: userPrompt
 			};
@@ -59,43 +288,24 @@ function userPromptMiddleware(options) {
 	};
 }
 //#endregion
-//#region src/capture-user-prompts.ts
-const INSTALLED_MARKER = "__alpicCaptureUserPromptsInstalled";
-/**
-* Captures the user's natural-language prompt behind each tool call on a vanilla
-* `@modelcontextprotocol/sdk` server. Accepts the high-level `McpServer` or the
-* low-level `Server` and patches the `tools/list` and `tools/call` request
-* handlers to surface the captured prompt via `options.handler` (or, when
-* `ALPIC_PROMPT_META_KEY` is set, via the response `_meta`).
-*
-* Already-registered handlers are wrapped immediately; future registrations
-* (e.g. tools added after this call) are wrapped via a `Map.set` proxy so order
-* of calls relative to `registerTool` does not matter.
-*/
-const captureUserPrompts = (server, options) => {
-	const handlers = ("server" in server ? server.server : server)?._requestHandlers;
-	if (!(handlers instanceof Map)) {
-		console.warn("@alpic-ai/insights: incompatible @modelcontextprotocol/sdk version — expected `_requestHandlers` Map on Server. Prompt capture disabled.");
-		return;
-	}
-	const marked = handlers;
-	if (marked[INSTALLED_MARKER]) return;
-	marked[INSTALLED_MARKER] = true;
-	const middleware = userPromptMiddleware(options);
-	const targets = new Set(["tools/list", "tools/call"]);
-	const wrap = (method, handler) => {
-		if (!targets.has(method)) return handler;
-		return async (...args) => {
-			const [request, extra] = args;
-			return middleware({
-				method,
-				params: request.params ?? {}
-			}, extra, () => handler(...args));
-		};
-	};
-	for (const [method, handler] of [...handlers]) handlers.set(method, wrap(method, handler));
-	const originalSet = handlers.set.bind(handlers);
-	handlers.set = (method, handler) => originalSet(method, wrap(method, handler));
+//#region src/capture-intents.ts
+/** Captures the user's natural-language intent behind each tool call by patching the server's `tools/list` and `tools/call` handlers, surfacing it via `options.handler` (or via the response `_meta` when `ALPIC_INTENT_META_KEY` is set). */
+const captureIntents = (server, options) => {
+	installCaptureMiddleware(server, {
+		middleware: intentMiddleware(options),
+		installedMarker: "__alpicCaptureIntentsInstalled",
+		disabledWarning: "Prompt capture disabled."
+	});
+};
+//#endregion
+//#region src/track.ts
+/** Enables custom analytics events by patching the server's `tools/call` handlers so tool handlers can call `extra.analytics.capture(...)` / `identify(...)`; pass `options.handler` to receive analytics when running outside Alpic. */
+const track = (server, options) => {
+	installCaptureMiddleware(server, {
+		middleware: analyticsMiddleware(options),
+		installedMarker: "__alpicTrackInstalled",
+		disabledWarning: "Analytics capture disabled."
+	});
 };
 //#endregion
-export { captureUserPrompts, userPromptMiddleware };
+export { analyticsMiddleware, captureFeedback, captureIntents, feedbackMiddleware, intentMiddleware, track };

package/dist/react/index.d.mts

@@ -0,0 +1,59 @@
+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, configuring itself from the widget host; events captured before configuration is available are buffered automatically. */
+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
+//#region src/react/auto-capture.d.ts
+/** The `$` prefix marks events emitted by the SDK itself 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

@@ -0,0 +1,274 @@
+import { createContext, useContext, useEffect, useRef, 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 = [];
+	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;
+		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;
+		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;
+		}
+		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/auto-capture.ts
+/** The `$` prefix marks events emitted by the SDK itself 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: the attribute value is the event 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) {
+	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, configuring itself from the widget host; events captured before configuration is available are buffered automatically. */
+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(() => {
+		return subscribeToAnalyticsStamp((stamp) => {
+			client.configure(stamp);
+		});
+	}, [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", onVisibilityChange);
+		window.addEventListener("pagehide", onPageHide);
+		return () => {
+			document.removeEventListener("visibilitychange", onVisibilityChange);
+			window.removeEventListener("pagehide", onPageHide);
+			client.flush();
+		};
+	}, [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
+	});
+}
+/** 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 { AUTO_EVENT, AlpicAnalytics, INTERACTION_ATTRIBUTE, useAnalytics };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpic-ai/insights",
-  "version": "0.0.0-dev.fffc79a",
+  "version": "0.0.0-dev.g009c2ea",
   "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,31 +22,45 @@
   "license": "ISC",
   "peerDependencies": {
     "@modelcontextprotocol/sdk": ">=1.29.0 <2",
-    "skybridge": ">=0.35.21"
+    "react": ">=18.0.0",
+    "skybridge": "^0.36.3 || ^1.0.0"
   },
   "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
     "skybridge": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@total-typescript/tsconfig": "^1.0.4",
-    "@types/node": "^25.6.0",
+    "@types/node": "^25.9.5",
+    "@types/react": "19.2.18",
+    "jsdom": "^30.0.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
     "shx": "^0.4.0",
-    "skybridge": "^0.35.21",
-    "tsdown": "^0.21.10",
+    "skybridge": "^1.3.5",
+    "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5",
-    "zod": "^4.3.6"
+    "vitest": "^4.1.10",
+    "zod": "^4.4.3"
   },
   "scripts": {
     "build": "shx rm -rf dist && tsdown",
+    "build:python": "cd python && uv build --no-sources",
     "format": "biome check --write --error-on-warnings .",
     "test": "pnpm run test:unit && pnpm run test:type && pnpm run test:format",
+    "test:python": "cd python && uv run --locked pytest",
+    "test:python:format": "cd python && uv run --locked ruff check . && uv run --locked ruff format --check .",
+    "test:python:smoke": "pnpm run build:python && cd python && uv run --isolated --no-project --with dist/*.whl scripts/smoke_test.py && uv run --isolated --no-project --with dist/*.tar.gz scripts/smoke_test.py",
     "test:unit": "vitest run",
     "test:format": "biome check --error-on-warnings .",
-    "test:type": "tsc --noEmit",
-    "publish:npm": "pnpm publish --tag \"${NPM_TAG}\" --access public --no-git-checks"
+    "test:type": "tsgo --noEmit",
+    "publish:npm": "../../scripts/publish-if-new.sh"
   }
 }