@visibe.ai/node 0.1.4

package/README.md

@@ -0,0 +1,330 @@
+<div align="center">
+
+# Visibe SDK for Node.js
+
+**Observability for AI agents.** Track costs, performance, and errors across your entire AI stack — whether you're using LangChain, LangGraph, Vercel AI, Anthropic, AWS Bedrock, or direct OpenAI calls.
+
+[![npm version](https://img.shields.io/npm/v/@visibe.ai/node.svg)](https://www.npmjs.com/package/@visibe.ai/node)
+![Node](https://img.shields.io/badge/node-18+-green.svg)
+![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)
+
+</div>
+
+---
+
+## 📦 Getting Started
+
+### Installation
+
+```bash
+npm install @visibe.ai/node
+```
+
+### Setup
+
+Set your API key:
+
+```bash
+export VISIBE_API_KEY=sk_live_your_api_key_here
+```
+
+Or in a `.env` file:
+
+```bash
+VISIBE_API_KEY=sk_live_your_api_key_here
+```
+
+### One line to instrument everything
+
+```typescript
+import { init } from '@visibe.ai/node'
+
+init()
+```
+
+That's it. Every OpenAI, Anthropic, LangChain, LangGraph, Vercel AI, and Bedrock client created after this call is automatically traced — no other code changes needed.
+
+---
+
+## 🧩 Integrations
+
+| Framework | Auto (`init()`) | Manual (`instrument()`) |
+|-----------|:-:|:-:|
+| **OpenAI** | ✅ | ✅ |
+| **Anthropic** | ✅ | ✅ |
+| **LangChain** | ✅ | ✅ |
+| **LangGraph** | ✅ | ✅ |
+| **Vercel AI** | ✅ | — |
+| **AWS Bedrock** | ✅ | ✅ |
+
+Also works with OpenAI-compatible providers: Azure OpenAI, Groq, Together.ai, DeepSeek, and others.
+
+### OpenAI
+
+```typescript
+import { init } from '@visibe.ai/node'
+import OpenAI from 'openai'
+
+init()
+
+const client = new OpenAI()
+const response = await client.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello!' }],
+})
+// Automatically traced — cost, tokens, duration, and content captured.
+```
+
+Streaming is also supported:
+
+```typescript
+const stream = await client.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Count to 5' }],
+  stream: true,
+})
+for await (const chunk of stream) {
+  process.stdout.write(chunk.choices[0]?.delta?.content ?? '')
+}
+// Token usage and cost captured when the stream is exhausted.
+```
+
+### Anthropic
+
+```typescript
+import { init } from '@visibe.ai/node'
+import Anthropic from '@anthropic-ai/sdk'
+
+init()
+
+const client = new Anthropic()
+const response = await client.messages.create({
+  model: 'claude-3-5-sonnet-20241022',
+  max_tokens: 100,
+  messages: [{ role: 'user', content: 'Hello!' }],
+})
+// Automatically traced.
+```
+
+### LangChain
+
+```typescript
+import { init } from '@visibe.ai/node'
+
+init()
+
+// require() AFTER init() so the instrumentation is already active
+const { ChatOpenAI }      = require('@langchain/openai')
+const { PromptTemplate }  = require('@langchain/core/prompts')
+const { StringOutputParser } = require('@langchain/core/output_parsers')
+const { RunnableSequence }   = require('@langchain/core/runnables')
+
+const chain = RunnableSequence.from([
+  PromptTemplate.fromTemplate('Summarize: {text}'),
+  new ChatOpenAI({ model: 'gpt-4o-mini' }),
+  new StringOutputParser(),
+])
+
+const result = await chain.invoke({ text: 'AI observability matters.' })
+// Full chain traced — LLM calls, token counts, and duration captured.
+```
+
+You can also use the `LangChainCallback` directly for explicit control:
+
+```typescript
+import { LangChainCallback } from '@visibe.ai/node/integrations/langchain'
+import { randomUUID } from 'node:crypto'
+
+const traceId  = randomUUID()
+const callback = new LangChainCallback({ visibe, traceId, agentName: 'my-agent' })
+
+const model = new ChatOpenAI({ model: 'gpt-4o-mini', callbacks: [callback] })
+await model.invoke([new HumanMessage('Hello!')])
+```
+
+### LangGraph
+
+```typescript
+import { init } from '@visibe.ai/node'
+
+init()  // must come BEFORE graph compilation
+
+const { StateGraph, END } = require('@langchain/langgraph')
+const { ChatOpenAI }      = require('@langchain/openai')
+const { HumanMessage }    = require('@langchain/core/messages')
+
+const model = new ChatOpenAI({ model: 'gpt-4o-mini' })
+
+const graph = new StateGraph({
+  channels: { messages: { value: (x, y) => x.concat(y), default: () => [] } },
+})
+  .addNode('research', async (state) => ({
+    messages: [await model.invoke([new HumanMessage('Research this topic')])],
+  }))
+  .addNode('summarise', async (state) => ({
+    messages: [await model.invoke([new HumanMessage('Summarise the research')])],
+  }))
+  .addEdge('__start__', 'research')
+  .addEdge('research', 'summarise')
+  .addEdge('summarise', END)
+  .compile()
+
+await graph.invoke({ messages: [] })
+// Each node's LLM calls traced, total cost and token counts rolled up per graph run.
+```
+
+### Vercel AI
+
+```typescript
+import { init } from '@visibe.ai/node'
+
+init()  // must come BEFORE require('ai')
+
+// require() AFTER init() so patchVercelAI() has replaced the exports
+const { generateText }  = require('ai')
+const { openai }        = require('@ai-sdk/openai')
+
+const result = await generateText({
+  model: openai('gpt-4o-mini'),
+  prompt: 'Write a haiku about observability.',
+})
+// Automatically traced — provider, model, tokens, and cost captured.
+```
+
+`streamText` and `generateObject` are also automatically patched.
+
+### AWS Bedrock
+
+```typescript
+import { init } from '@visibe.ai/node'
+import { BedrockRuntimeClient, ConverseCommand } from '@aws-sdk/client-bedrock-runtime'
+
+init()
+
+const client = new BedrockRuntimeClient({ region: 'us-east-1' })
+const response = await client.send(new ConverseCommand({
+  modelId: 'anthropic.claude-3-haiku-20240307-v1:0',
+  messages: [{ role: 'user', content: [{ text: 'Hello!' }] }],
+}))
+// Automatically traced. Works with all models available via Bedrock —
+// Claude, Nova, Llama, Mistral, and more.
+```
+
+Supports `ConverseCommand`, `ConverseStreamCommand`, `InvokeModelCommand`, and `InvokeModelWithResponseStreamCommand`.
+
+---
+
+## ⚙️ Configuration
+
+```typescript
+import { init } from '@visibe.ai/node'
+
+init({
+  apiKey:       'sk_live_abc123',          // or set VISIBE_API_KEY env var
+  frameworks:   ['openai', 'langgraph'],   // limit to specific frameworks
+  contentLimit: 500,                       // max chars for LLM content in traces
+  debug:        true,                      // enable debug logging
+})
+```
+
+### Options
+
+| Option | Type | Description | Default |
+|--------|------|-------------|---------|
+| `apiKey` | `string` | Your Visibe API key | `VISIBE_API_KEY` env var |
+| `apiUrl` | `string` | Override API endpoint | `https://api.visibe.ai` |
+| `frameworks` | `string[]` | Limit auto-instrumentation to specific frameworks | All detected |
+| `contentLimit` | `number` | Max chars for LLM/tool content in spans | `1000` |
+| `debug` | `boolean` | Enable debug logging | `false` |
+| `sessionId` | `string` | Tag all traces with a session ID | — |
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `VISIBE_API_KEY` | Your API key (required) | — |
+| `VISIBE_API_URL` | Override API endpoint | `https://api.visibe.ai` |
+| `VISIBE_CONTENT_LIMIT` | Max chars for LLM/tool content in spans | `1000` |
+| `VISIBE_DEBUG` | Enable debug logging (`1` to enable) | `0` |
+
+---
+
+## 📊 What Gets Tracked
+
+| Metric | Description |
+|--------|-------------|
+| **Cost** | Total spend + per-call cost breakdown using current model pricing |
+| **Tokens** | Input/output tokens per LLM call |
+| **Duration** | Total time + time per step |
+| **Tools** | Which tools were used, duration, success/failure |
+| **Errors** | When and where things failed, with error type and message |
+| **Spans** | Full execution timeline with LLM calls, tool calls, and agent events |
+
+---
+
+## 🔧 Manual Instrumentation
+
+For cases where you need explicit control — instrumenting a specific client, grouping multiple calls into a named trace, or using Visibe without `init()`.
+
+### Instrument a specific client
+
+```typescript
+import { Visibe } from '@visibe.ai/node'
+import OpenAI from 'openai'
+
+const visibe = new Visibe({ apiKey: 'sk_live_abc123' })
+const client = new OpenAI()
+
+visibe.instrument(client, { name: 'my-agent' })
+
+await client.chat.completions.create({
+  model: 'gpt-4o-mini',
+  messages: [{ role: 'user', content: 'Hello!' }],
+})
+// Each call creates its own trace named 'my-agent'.
+```
+
+### Group multiple calls into one trace
+
+```typescript
+import { Visibe } from '@visibe.ai/node'
+import OpenAI from 'openai'
+
+const visibe = new Visibe()
+const client = new OpenAI()
+
+await visibe.track(client, 'my-conversation', async () => {
+  await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [...] })
+  await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [...] })
+})
+// Both calls sent as one grouped trace with combined cost and token totals.
+```
+
+### Remove instrumentation
+
+```typescript
+visibe.uninstrument(client)
+```
+
+### Graceful shutdown
+
+The SDK registers `SIGTERM` and `SIGINT` handlers automatically. For long-running scripts where you want to ensure all spans are flushed before exit:
+
+```typescript
+import { shutdown } from '@visibe.ai/node'
+
+await shutdown()
+```
+
+---
+
+## 🔗 Resources
+
+- [npm Package](https://www.npmjs.com/package/@visibe.ai/node) — Install the latest version
+- [Visibe Dashboard](https://app.visibe.ai) — View your traces and analytics
+
+---
+
+## 📃 License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/cjs/api.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpanBatcher = exports.APIClient = void 0;
+const DEFAULT_API_URL = 'https://api.visibe.ai';
+const DEFAULT_TIMEOUT_MS = 10000;
+class APIClient {
+    constructor(options) {
+        this.apiUrl = options.apiUrl ?? DEFAULT_API_URL;
+        this.apiKey = options.apiKey;
+        this.timeout = options.timeout ?? DEFAULT_TIMEOUT_MS;
+        this._enabled = Boolean(options.apiKey);
+        if (!this._enabled) {
+            process.emitWarning('[Visibe] No API key provided — tracing is disabled. Set VISIBE_API_KEY or pass apiKey= to enable.', { type: 'VisibleSDKWarning', code: 'VISIBE_NO_API_KEY' });
+        }
+    }
+    async _request(method, path, body) {
+        if (!this._enabled)
+            return false;
+        try {
+            const response = await fetch(`${this.apiUrl}${path}`, {
+                method,
+                headers: {
+                    'Content-Type': 'application/json',
+                    'Authorization': `Bearer ${this.apiKey}`,
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: AbortSignal.timeout(this.timeout),
+            });
+            return response.ok;
+        }
+        catch {
+            return false; // fire-and-forget — never throw
+        }
+    }
+    async createTrace(data) {
+        return this._request('POST', '/api/traces', data);
+    }
+    async sendSpan(traceId, span) {
+        return this._request('POST', `/api/traces/${traceId}/spans`, span);
+    }
+    async sendSpansBatch(traceId, spans) {
+        return this._request('POST', `/api/traces/${traceId}/spans/batch`, { spans });
+    }
+    async completeTrace(traceId, data) {
+        return this._request('PATCH', `/api/traces/${traceId}`, data);
+    }
+}
+exports.APIClient = APIClient;
+// ---------------------------------------------------------------------------
+class SpanBatcher {
+    constructor(api) {
+        this.api = api;
+        this.buffer = [];
+        this.batchSize = 50;
+        this.flushInterval = 2000; // ms
+        this.timer = setInterval(() => this.flush(), this.flushInterval);
+        // CRITICAL: unref() so the timer does not prevent the process from exiting
+        // once all user code has finished.
+        this.timer.unref();
+    }
+    add(traceId, span) {
+        // Fast-path: drop immediately when there is no API key — don't buffer.
+        if (!this.api._enabled)
+            return;
+        this.buffer.push({ traceId, span });
+        if (this.buffer.length >= this.batchSize)
+            this.flush();
+    }
+    flush() {
+        if (this.buffer.length === 0)
+            return;
+        // Drain atomically — safe because Node.js is single-threaded.
+        const batch = this.buffer.splice(0);
+        // Group spans by traceId so we make one batch request per active trace.
+        const byTrace = new Map();
+        for (const { traceId, span } of batch) {
+            const arr = byTrace.get(traceId) ?? [];
+            arr.push(span);
+            byTrace.set(traceId, arr);
+        }
+        for (const [traceId, spans] of byTrace) {
+            this.api.sendSpansBatch(traceId, spans).catch(() => { }); // fire-and-forget
+        }
+    }
+    async shutdown() {
+        clearInterval(this.timer);
+        this.flush();
+        // Give in-flight requests up to 300 ms to complete before the process exits.
+        await new Promise(resolve => setTimeout(resolve, 300));
+    }
+}
+exports.SpanBatcher = SpanBatcher;

package/dist/cjs/client.js

@@ -0,0 +1,242 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Visibe = void 0;
+const node_crypto_1 = require("node:crypto");
+const api_1 = require("./api");
+const group_context_1 = require("./integrations/group-context");
+const utils_1 = require("./utils");
+class Visibe {
+    constructor(options) {
+        // Map of instrumented clients to their cleanup functions.
+        this._instrumented = new Map();
+        const apiKey = options.apiKey ?? process.env['VISIBE_API_KEY'];
+        const apiUrl = options.apiUrl ?? process.env['VISIBE_API_URL'];
+        const debug = options.debug ?? process.env['VISIBE_DEBUG'] === '1';
+        const limit = options.contentLimit
+            ?? (process.env['VISIBE_CONTENT_LIMIT'] ? Number(process.env['VISIBE_CONTENT_LIMIT']) : undefined)
+            ?? utils_1.LLM_CONTENT_LIMIT;
+        this.contentLimit = limit;
+        this.sessionId = options.sessionId;
+        this.debug = debug;
+        this.apiClient = new api_1.APIClient({ apiKey, apiUrl });
+        this.batcher = new api_1.SpanBatcher(this.apiClient);
+    }
+    // ---------------------------------------------------------------------------
+    // instrument() — wrap a client so each call creates its own trace.
+    // ---------------------------------------------------------------------------
+    instrument(client, options) {
+        if (this._instrumented.has(client))
+            return; // already patched
+        const name = options?.name ?? 'agent';
+        // Detect which kind of client this is and apply the right integration.
+        // Integrations are resolved lazily here to avoid circular imports at module load.
+        const restore = applyIntegration(client, name, this);
+        if (restore) {
+            this._instrumented.set(client, restore);
+        }
+    }
+    uninstrument(client) {
+        const restore = this._instrumented.get(client);
+        if (restore) {
+            restore();
+            this._instrumented.delete(client);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // track() — group multiple LLM calls into a single named trace.
+    //
+    // Instruments the client if not already done, then runs fn() inside an
+    // AsyncLocalStorage context so all integrations automatically route their
+    // spans into the shared traceId and report token/cost totals back here.
+    // ---------------------------------------------------------------------------
+    async track(client, 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: detectFrameworkName(client),
+            started_at: startedAt,
+            ...(this.sessionId ? { session_id: this.sessionId } : {}),
+        });
+        // Accumulators updated by the group context callbacks (called from integrations).
+        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++; },
+        };
+        // Temporarily instrument client if not already done so that the integration
+        // patch is in place for the duration of fn().
+        const wasInstrumented = this._instrumented.has(client);
+        if (!wasInstrumented) {
+            this.instrument(client, { name });
+        }
+        // Run fn() inside the group ALS context.  All instrumented integrations
+        // check activeGroupTraceStorage.getStore() — when set they skip their own
+        // createTrace/completeTrace calls and route spans into the shared traceId.
+        return group_context_1.activeGroupTraceStorage.run(groupCtx, async () => {
+            let status = 'completed';
+            try {
+                return await fn();
+            }
+            catch (err) {
+                status = 'failed';
+                throw err;
+            }
+            finally {
+                if (!wasInstrumented) {
+                    this.uninstrument(client);
+                }
+                const durationMs = Date.now() - startMs;
+                // CRITICAL ORDER: flush spans first, then complete the trace.
+                // The backend computes all breakdowns from spans at read time.
+                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);
+            }
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // flushSpans() — called by shutdown() in index.ts.
+    // ---------------------------------------------------------------------------
+    flushSpans() {
+        this.batcher.flush();
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers used by integrations.
+    // ---------------------------------------------------------------------------
+    buildLLMSpan(opts) {
+        const cost = (0, utils_1.calculateCost)(opts.model, opts.inputTokens, opts.outputTokens);
+        return {
+            span_id: opts.spanId,
+            ...(opts.parentSpanId ? { parent_span_id: opts.parentSpanId } : {}),
+            type: 'llm_call',
+            timestamp: new Date().toISOString(),
+            agent_name: opts.agentName,
+            model: opts.model,
+            provider: (0, utils_1.detectProvider)(opts.model),
+            status: opts.status,
+            description: `LLM Call using ${opts.model}`,
+            input_tokens: opts.inputTokens,
+            output_tokens: opts.outputTokens,
+            cost,
+            duration_ms: opts.durationMs,
+            input_text: (0, utils_1.truncate)(opts.inputText, this.contentLimit),
+            output_text: (0, utils_1.truncate)(opts.outputText, this.contentLimit),
+        };
+    }
+    buildToolSpan(opts) {
+        return {
+            span_id: opts.spanId,
+            ...(opts.parentSpanId ? { parent_span_id: opts.parentSpanId } : {}),
+            type: 'tool_call',
+            timestamp: new Date().toISOString(),
+            tool_name: opts.toolName,
+            agent_name: opts.agentName,
+            status: opts.status,
+            duration_ms: opts.durationMs,
+            input_text: (0, utils_1.truncate)(opts.inputText, 500),
+            output_text: (0, utils_1.truncate)(opts.outputText, 500),
+        };
+    }
+    buildErrorSpan(opts) {
+        return {
+            span_id: opts.spanId,
+            type: 'error',
+            timestamp: new Date().toISOString(),
+            description: `Error: ${opts.errorType}`,
+            error_type: opts.errorType,
+            error_message: (0, utils_1.truncate)(opts.errorMessage, 500),
+            duration_ms: opts.durationMs ?? 10,
+        };
+    }
+    buildAgentStartSpan(opts) {
+        return {
+            span_id: opts.spanId,
+            type: 'agent_start', // EXACT string — backend validates this
+            timestamp: new Date().toISOString(),
+            agent_name: opts.agentName,
+            description: `Agent started: ${opts.agentName}`,
+        };
+    }
+}
+exports.Visibe = Visibe;
+// ---------------------------------------------------------------------------
+// Helpers (module-private)
+// ---------------------------------------------------------------------------
+function printTraceSummary(summary, sent) {
+    const durationSec = (summary.durationMs / 1000).toFixed(1);
+    const tokens = summary.totalTokens.toLocaleString();
+    const cost = `$${summary.totalCost.toFixed(6)}`;
+    const sentStr = sent ? 'OK' : 'FAILED';
+    console.log(`[Visibe] Trace: ${summary.name} | ${summary.llmCallCount} LLM calls | ${tokens} tokens | ${cost} | ${durationSec}s | ${summary.toolCallCount} tool calls | status: ${summary.status} | sent: ${sentStr}`);
+}
+// Detect a human-readable framework name from a client instance.
+// Used in createTrace() payload. Integrations can refine this later.
+function detectFrameworkName(client) {
+    const name = client?.constructor?.name ?? '';
+    if (name === 'OpenAI')
+        return 'openai';
+    if (name === 'Anthropic')
+        return 'anthropic';
+    if (name === 'BedrockRuntimeClient')
+        return 'bedrock';
+    return 'unknown';
+}
+// Apply the correct integration for a given client instance.
+// Returns a restore function, or null if the client type is unrecognised.
+function applyIntegration(client, name, visibe) {
+    // Integrations are loaded lazily to avoid import errors when the peer
+    // dependency is not installed.  Each integration module exports a
+    // `patchClient(client, name, visibe)` that returns a restore function.
+    const constructorName = client?.constructor?.name ?? '';
+    try {
+        if (constructorName === 'OpenAI') {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { patchOpenAIClient } = require('./integrations/openai');
+            return patchOpenAIClient(client, name, visibe);
+        }
+        if (constructorName === 'Anthropic') {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { patchAnthropicClient } = require('./integrations/anthropic');
+            return patchAnthropicClient(client, name, visibe);
+        }
+        if (constructorName === 'BedrockRuntimeClient') {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            const { patchBedrockClient } = require('./integrations/bedrock');
+            return patchBedrockClient(client, name, visibe);
+        }
+    }
+    catch {
+        // Integration module not available or patch threw — never crash user code.
+    }
+    return null;
+}