@alpic-ai/insights 1.161.0 → 1.162.0

package/dist/index.d.mts

@@ -7,33 +7,17 @@ interface PromptData {
 }
 interface IntentMiddlewareOptions {
   handler?: (prompt: PromptData) => Promise<void> | void;
-  /**
-   * If provided, only these tool names will have the `user_intent` field injected and their
-   * prompts captured. All other tools are left untouched.
-   */
+  /** When provided, only these tool names have the `user_intent` field injected and their prompts captured; all other tools are left untouched. */
   tools?: string[];
-  /**
-   * Mapping of tool names to argument names whose values should be captured as the intent.
-   * Use this when the tool already has an argument (e.g. `query`, `question`) that conveys user
-   * intent. For tools in this mapping, the synthetic `user_intent` argument is not injected into the
-   * schema and the argument's value is read straight from the tool call arguments without being stripped.
-   */
+  /** 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(...)`.
- */
+/** 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_intent` from the original user message
- * (the server has no other way to access it).
- */
+/** 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
@@ -49,16 +33,10 @@ interface CaptureOptions {
 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.
-   */
+  /** 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.
- */
+/** 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;
 }
@@ -74,13 +52,7 @@ 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. 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.
- */
+/** 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
@@ -89,48 +61,22 @@ interface FeedbackData {
   source: "model" | "user";
 }
 interface FeedbackMiddlewareOptions {
-  /**
-   * Custom handler invoked with the user's feedback. When provided, the middleware still attaches the feedback to the response `_meta`.
-   * The handler runs **in addition to** Alpic's dashboard delivery, feedback are still captured when deployed on Alpic.
-   */
+  /** 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;
 }
-/**
- * Lets MCP server builders collect qualitative feedback from end users about their
- * tool/server. Injects a `send_feedback` tool at `tools/list` time and intercepts calls
- * to it at `tools/call` time. The tool has no handler on the server. The middleware
- * short-circuits the call and either invokes the provided `handler` or attaches the
- * feedback to the response `_meta`.
- */
+/** 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 into a vanilla `@modelcontextprotocol/sdk`
- * server and captures feedback submissions. Accepts the high-level `McpServer`
- * or the low-level `Server` and patches the `tools/list` and `tools/call`
- * request handlers to surface captured feedback via `options.handler` (or,
- * when `ALPIC_FEEDBACK_META_KEY` is set, via the response `_meta`).
- */
+/** 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 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 intent via `options.handler` (or, when
- * `ALPIC_INTENT_META_KEY` is set, via the response `_meta`).
- */
+/** 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/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(...)`.
- * Pass a handler in `options` to receive analytics when running outside Alpic.
- */
+/** 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 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

@@ -44,13 +44,7 @@ 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. 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.
-*/
+/** 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();
@@ -102,13 +96,7 @@ const FEEDBACK_OUTPUT_SCHEMA = {
 	additionalProperties: false
 };
 const FEEDBACK_STRUCTURED_CONTENT = { status: "received" };
-/**
-* Lets MCP server builders collect qualitative feedback from end users about their
-* tool/server. Injects a `send_feedback` tool at `tools/list` time and intercepts calls
-* to it at `tools/call` time. The tool has no handler on the server. The middleware
-* short-circuits the call and either invokes the provided `handler` or attaches the
-* feedback to the response `_meta`.
-*/
+/** 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;
@@ -187,15 +175,7 @@ function feedbackMiddleware(options) {
 }
 //#endregion
 //#region src/install-capture-middleware.ts
-/**
-* Patches the `tools/list` and `tools/call` request handlers of a vanilla
-* `@modelcontextprotocol/sdk` server (high-level `McpServer` or low-level
-* `Server`) to run the given middleware.
-*
-* 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.
-*/
+/** 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)) {
@@ -222,13 +202,7 @@ const installCaptureMiddleware = (server, { middleware, installedMarker, disable
 };
 //#endregion
 //#region src/capture-feedback.ts
-/**
-* Injects a `send_feedback` tool into a vanilla `@modelcontextprotocol/sdk`
-* server and captures feedback submissions. Accepts the high-level `McpServer`
-* or the low-level `Server` and patches the `tools/list` and `tools/call`
-* request handlers to surface captured feedback via `options.handler` (or,
-* when `ALPIC_FEEDBACK_META_KEY` is set, via the response `_meta`).
-*/
+/** 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),
@@ -239,12 +213,7 @@ const captureFeedback = (server, options) => {
 //#endregion
 //#region src/intent-middleware.ts
 const USER_INTENT_FIELD = "user_intent";
-/**
-* 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_intent` from the original user message
-* (the server has no other way to access it).
-*/
+/** 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;
@@ -320,13 +289,7 @@ Before sending, strip all personally identifiable information (names, emails, ph
 }
 //#endregion
 //#region src/capture-intents.ts
-/**
-* Captures the user's natural-language intent 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 intent via `options.handler` (or, when
-* `ALPIC_INTENT_META_KEY` is set, via the response `_meta`).
-*/
+/** 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),
@@ -336,12 +299,7 @@ const captureIntents = (server, options) => {
 };
 //#endregion
 //#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(...)`.
-* Pass a handler in `options` to receive analytics when running outside Alpic.
-*/
+/** 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),

package/dist/react/index.d.mts

@@ -39,21 +39,13 @@ interface AlpicAnalyticsProps {
   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.
- */
+/** 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
-/**
- * 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.
- */
+/** 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";

package/dist/react/index.mjs

@@ -72,11 +72,7 @@ function isSameStamp(left, right) {
 }
 //#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.
-*/
+/** 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",
@@ -88,10 +84,7 @@ const AUTO_EVENT = {
 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.
-*/
+/** 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}]`);
@@ -217,11 +210,7 @@ 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.
-*/
+/** 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alpic-ai/insights",
-  "version": "1.161.0",
+  "version": "1.162.0",
   "description": "User insights middlewares for Alpic-hosted MCP servers",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -34,17 +34,17 @@
     }
   },
   "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.9.5",
-    "@types/react": "19.2.17",
+    "@types/react": "19.2.18",
     "jsdom": "^30.0.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "shx": "^0.4.0",
-    "skybridge": "^1.3.0",
+    "skybridge": "^1.3.2",
     "tsdown": "^0.22.14",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
@@ -52,8 +52,12 @@
   },
   "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": "tsgo --noEmit",