@visibe.ai/node 0.1.24 → 0.1.25

package/dist/cjs/client.js

@@ -132,6 +132,170 @@ class Visibe {
         });
     }
     // ---------------------------------------------------------------------------
+    // runWithSession() — group all auto-instrumented LLM calls inside fn()
+    // into a single named trace.  Unlike track(), no specific client is required;
+    // all already-instrumented clients are automatically captured.
+    // ---------------------------------------------------------------------------
+    async runWithSession(name, fn) {
+        const traceId = (0, node_crypto_1.randomUUID)();
+        const startedAt = new Date().toISOString();
+        const startMs = Date.now();
+        await this.apiClient.createTrace({
+            trace_id: traceId,
+            name,
+            framework: 'session',
+            started_at: startedAt,
+            ...(this.sessionId ? { session_id: this.sessionId } : {}),
+        });
+        let llmCallCount = 0;
+        let toolCallCount = 0;
+        let totalInput = 0;
+        let totalOutput = 0;
+        let totalCost = 0;
+        const groupCtx = {
+            traceId,
+            onLLMSpan: (inputTokens, outputTokens, cost) => {
+                llmCallCount++;
+                totalInput += inputTokens;
+                totalOutput += outputTokens;
+                totalCost += cost;
+            },
+            onToolSpan: () => { toolCallCount++; },
+        };
+        return group_context_1.activeGroupTraceStorage.run(groupCtx, async () => {
+            let status = 'completed';
+            try {
+                return await fn();
+            }
+            catch (err) {
+                status = 'failed';
+                throw err;
+            }
+            finally {
+                const durationMs = Date.now() - startMs;
+                // CRITICAL ORDER: flush spans first, then complete the trace.
+                this.batcher.flush();
+                const sent = await this.apiClient.completeTrace(traceId, {
+                    status,
+                    ended_at: new Date().toISOString(),
+                    duration_ms: durationMs,
+                    llm_call_count: llmCallCount,
+                    total_cost: parseFloat(totalCost.toFixed(6)),
+                    total_tokens: totalInput + totalOutput,
+                    total_input_tokens: totalInput,
+                    total_output_tokens: totalOutput,
+                });
+                printTraceSummary({
+                    name,
+                    llmCallCount,
+                    toolCallCount,
+                    totalTokens: totalInput + totalOutput,
+                    totalCost,
+                    durationMs,
+                    status,
+                }, sent);
+            }
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // middleware() — Express / Connect / Fastify compatible middleware.
+    //
+    // Groups every LLM call made during a single HTTP request into one trace.
+    // Uses AsyncLocalStorage so concurrent requests are fully isolated — each
+    // request gets its own trace regardless of how many are in flight at once.
+    //
+    // Usage:
+    //   app.use(visibe.middleware())
+    //   app.use(visibe.middleware({ name: (req) => `${req.method} ${req.url}` }))
+    // ---------------------------------------------------------------------------
+    middleware(options) {
+        return (req, res, next) => {
+            // No-op immediately if the SDK is disabled (no/invalid API key).
+            if (!this.apiClient._enabled) {
+                next();
+                return;
+            }
+            const traceId = (0, node_crypto_1.randomUUID)();
+            const startedAt = new Date().toISOString();
+            const startMs = Date.now();
+            // Resolve the trace name from options or fall back to "METHOD /url".
+            const name = typeof options?.name === 'function'
+                ? options.name(req)
+                : options?.name ?? `${req.method ?? 'HTTP'} ${req.url ?? '/'}`;
+            // Fire createTrace without awaiting — we own the traceId so spans
+            // can be buffered safely until the trace creation lands on the backend.
+            // Awaiting here would add a network round-trip to every request.
+            this.apiClient.createTrace({
+                trace_id: traceId,
+                name,
+                framework: 'http',
+                started_at: startedAt,
+                ...(this.sessionId ? { session_id: this.sessionId } : {}),
+            }).catch(() => { });
+            let llmCallCount = 0;
+            let toolCallCount = 0;
+            let totalInput = 0;
+            let totalOutput = 0;
+            let totalCost = 0;
+            const groupCtx = {
+                traceId,
+                onLLMSpan: (inputTokens, outputTokens, cost) => {
+                    llmCallCount++;
+                    totalInput += inputTokens;
+                    totalOutput += outputTokens;
+                    totalCost += cost;
+                },
+                onToolSpan: () => { toolCallCount++; },
+            };
+            // Guard against both 'finish' and 'close' firing for the same response.
+            // 'finish' fires when all data is written; 'close' fires when the
+            // underlying connection is closed (e.g. client disconnected early).
+            // We only want to complete the trace once.
+            let completed = false;
+            const complete = () => {
+                if (completed)
+                    return;
+                completed = true;
+                const durationMs = Date.now() - startMs;
+                // Treat any 4xx/5xx as a failed trace.
+                const status = res.statusCode >= 400 ? 'failed' : 'completed';
+                // Flush buffered spans before completing the trace so the backend
+                // has all spans available when it processes the PATCH request.
+                this.batcher.flush();
+                this.apiClient.completeTrace(traceId, {
+                    status,
+                    ended_at: new Date().toISOString(),
+                    duration_ms: durationMs,
+                    llm_call_count: llmCallCount,
+                    total_cost: parseFloat(totalCost.toFixed(6)),
+                    total_tokens: totalInput + totalOutput,
+                    total_input_tokens: totalInput,
+                    total_output_tokens: totalOutput,
+                }).catch(() => { });
+                // Only print in debug mode — middleware runs on every request and
+                // would produce too much noise in production by default.
+                if (this.debug) {
+                    printTraceSummary({
+                        name,
+                        llmCallCount,
+                        toolCallCount,
+                        totalTokens: totalInput + totalOutput,
+                        totalCost,
+                        durationMs,
+                        status,
+                    }, true);
+                }
+            };
+            // Run next() inside the ALS context so all async operations spawned
+            // by the route handler inherit this request's groupCtx automatically.
+            group_context_1.activeGroupTraceStorage.run(groupCtx, () => {
+                res.on('finish', complete);
+                res.on('close', complete);
+                next();
+            });
+        };
+    }
+    // ---------------------------------------------------------------------------
     // flushSpans() — called by shutdown() in index.ts.
     // ---------------------------------------------------------------------------
     flushSpans() {

package/dist/esm/client.js

@@ -129,6 +129,170 @@ export class Visibe {
         });
     }
     // ---------------------------------------------------------------------------
+    // runWithSession() — group all auto-instrumented LLM calls inside fn()
+    // into a single named trace.  Unlike track(), no specific client is required;
+    // all already-instrumented clients are automatically captured.
+    // ---------------------------------------------------------------------------
+    async runWithSession(name, fn) {
+        const traceId = randomUUID();
+        const startedAt = new Date().toISOString();
+        const startMs = Date.now();
+        await this.apiClient.createTrace({
+            trace_id: traceId,
+            name,
+            framework: 'session',
+            started_at: startedAt,
+            ...(this.sessionId ? { session_id: this.sessionId } : {}),
+        });
+        let llmCallCount = 0;
+        let toolCallCount = 0;
+        let totalInput = 0;
+        let totalOutput = 0;
+        let totalCost = 0;
+        const groupCtx = {
+            traceId,
+            onLLMSpan: (inputTokens, outputTokens, cost) => {
+                llmCallCount++;
+                totalInput += inputTokens;
+                totalOutput += outputTokens;
+                totalCost += cost;
+            },
+            onToolSpan: () => { toolCallCount++; },
+        };
+        return activeGroupTraceStorage.run(groupCtx, async () => {
+            let status = 'completed';
+            try {
+                return await fn();
+            }
+            catch (err) {
+                status = 'failed';
+                throw err;
+            }
+            finally {
+                const durationMs = Date.now() - startMs;
+                // CRITICAL ORDER: flush spans first, then complete the trace.
+                this.batcher.flush();
+                const sent = await this.apiClient.completeTrace(traceId, {
+                    status,
+                    ended_at: new Date().toISOString(),
+                    duration_ms: durationMs,
+                    llm_call_count: llmCallCount,
+                    total_cost: parseFloat(totalCost.toFixed(6)),
+                    total_tokens: totalInput + totalOutput,
+                    total_input_tokens: totalInput,
+                    total_output_tokens: totalOutput,
+                });
+                printTraceSummary({
+                    name,
+                    llmCallCount,
+                    toolCallCount,
+                    totalTokens: totalInput + totalOutput,
+                    totalCost,
+                    durationMs,
+                    status,
+                }, sent);
+            }
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // middleware() — Express / Connect / Fastify compatible middleware.
+    //
+    // Groups every LLM call made during a single HTTP request into one trace.
+    // Uses AsyncLocalStorage so concurrent requests are fully isolated — each
+    // request gets its own trace regardless of how many are in flight at once.
+    //
+    // Usage:
+    //   app.use(visibe.middleware())
+    //   app.use(visibe.middleware({ name: (req) => `${req.method} ${req.url}` }))
+    // ---------------------------------------------------------------------------
+    middleware(options) {
+        return (req, res, next) => {
+            // No-op immediately if the SDK is disabled (no/invalid API key).
+            if (!this.apiClient._enabled) {
+                next();
+                return;
+            }
+            const traceId = randomUUID();
+            const startedAt = new Date().toISOString();
+            const startMs = Date.now();
+            // Resolve the trace name from options or fall back to "METHOD /url".
+            const name = typeof options?.name === 'function'
+                ? options.name(req)
+                : options?.name ?? `${req.method ?? 'HTTP'} ${req.url ?? '/'}`;
+            // Fire createTrace without awaiting — we own the traceId so spans
+            // can be buffered safely until the trace creation lands on the backend.
+            // Awaiting here would add a network round-trip to every request.
+            this.apiClient.createTrace({
+                trace_id: traceId,
+                name,
+                framework: 'http',
+                started_at: startedAt,
+                ...(this.sessionId ? { session_id: this.sessionId } : {}),
+            }).catch(() => { });
+            let llmCallCount = 0;
+            let toolCallCount = 0;
+            let totalInput = 0;
+            let totalOutput = 0;
+            let totalCost = 0;
+            const groupCtx = {
+                traceId,
+                onLLMSpan: (inputTokens, outputTokens, cost) => {
+                    llmCallCount++;
+                    totalInput += inputTokens;
+                    totalOutput += outputTokens;
+                    totalCost += cost;
+                },
+                onToolSpan: () => { toolCallCount++; },
+            };
+            // Guard against both 'finish' and 'close' firing for the same response.
+            // 'finish' fires when all data is written; 'close' fires when the
+            // underlying connection is closed (e.g. client disconnected early).
+            // We only want to complete the trace once.
+            let completed = false;
+            const complete = () => {
+                if (completed)
+                    return;
+                completed = true;
+                const durationMs = Date.now() - startMs;
+                // Treat any 4xx/5xx as a failed trace.
+                const status = res.statusCode >= 400 ? 'failed' : 'completed';
+                // Flush buffered spans before completing the trace so the backend
+                // has all spans available when it processes the PATCH request.
+                this.batcher.flush();
+                this.apiClient.completeTrace(traceId, {
+                    status,
+                    ended_at: new Date().toISOString(),
+                    duration_ms: durationMs,
+                    llm_call_count: llmCallCount,
+                    total_cost: parseFloat(totalCost.toFixed(6)),
+                    total_tokens: totalInput + totalOutput,
+                    total_input_tokens: totalInput,
+                    total_output_tokens: totalOutput,
+                }).catch(() => { });
+                // Only print in debug mode — middleware runs on every request and
+                // would produce too much noise in production by default.
+                if (this.debug) {
+                    printTraceSummary({
+                        name,
+                        llmCallCount,
+                        toolCallCount,
+                        totalTokens: totalInput + totalOutput,
+                        totalCost,
+                        durationMs,
+                        status,
+                    }, true);
+                }
+            };
+            // Run next() inside the ALS context so all async operations spawned
+            // by the route handler inherit this request's groupCtx automatically.
+            activeGroupTraceStorage.run(groupCtx, () => {
+                res.on('finish', complete);
+                res.on('close', complete);
+                next();
+            });
+        };
+    }
+    // ---------------------------------------------------------------------------
     // flushSpans() — called by shutdown() in index.ts.
     // ---------------------------------------------------------------------------
     flushSpans() {

package/dist/types/client.d.ts

@@ -1,5 +1,5 @@
 import { APIClient, SpanBatcher } from './api';
-import type { InitOptions } from './types';
+import type { InitOptions, MiddlewareOptions, MiddlewareRequest, MiddlewareResponse } from './types';
 export type { InitOptions };
 export declare class Visibe {
     readonly apiClient: APIClient;
@@ -14,6 +14,8 @@ export declare class Visibe {
     }): void;
     uninstrument(client: object): void;
     track<T>(client: object, name: string, fn: () => Promise<T>): Promise<T>;
+    runWithSession<T>(name: string, fn: () => Promise<T>): Promise<T>;
+    middleware(options?: MiddlewareOptions): (req: MiddlewareRequest, res: MiddlewareResponse, next: () => void) => void;
     flushSpans(): void;
     buildLLMSpan(opts: {
         spanId: string;

package/dist/types/index.d.ts

@@ -4,4 +4,4 @@ export declare function detectFrameworks(): Record<string, boolean>;
 export declare function init(options?: InitOptions): Visibe;
 export declare function shutdown(): Promise<void>;
 export { Visibe } from './client';
-export type { InitOptions, TraceSummary, SpanType, SpanStatus, TraceStatus, LLMProvider } from './types';
+export type { InitOptions, MiddlewareOptions, MiddlewareRequest, MiddlewareResponse, TraceSummary, SpanType, SpanStatus, TraceStatus, LLMProvider } from './types';

package/dist/types/types/index.d.ts

@@ -19,3 +19,20 @@ export interface TraceSummary {
     durationMs: number;
     status: TraceStatus;
 }
+export interface MiddlewareRequest {
+    method?: string;
+    url?: string;
+}
+export interface MiddlewareResponse {
+    statusCode: number;
+    on(event: 'finish' | 'close', listener: () => void): this;
+}
+export interface MiddlewareOptions {
+    /**
+     * Trace name for each request.
+     * - Omit for the default: "METHOD /url"  (e.g. "POST /api/chat")
+     * - Pass a string for a fixed name
+     * - Pass a function to derive the name from the request
+     */
+    name?: string | ((req: MiddlewareRequest) => string);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@visibe.ai/node",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "description": "AI Agent Observability — Track OpenAI, LangChain, LangGraph, Bedrock, Vercel AI, Anthropic",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",