@alpic-ai/insights 1.157.3 → 1.159.0

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
@@ -356,10 +364,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpic-ai/insights",
-  "version": "1.157.3",
+  "version": "1.159.0",
   "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.9",
+    "skybridge": "^1.3.0",
+    "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3"