trodo-node 2.4.3 → 2.5.0

package/README.md

@@ -1,513 +1,513 @@
-# trodo-node
-
-Server-side Node.js SDK for [Trodo Analytics](https://trodo.ai). Track backend events, identify users, manage people/groups, and instrument AI agents — all unified with your frontend data under the same `siteId`.
-
-## Installation
-
-```bash
-npm install trodo-node
-```
-
-Node 18+ uses native `fetch`. For Node 16/17, install the optional peer dependency:
-
-```bash
-npm install trodo-node node-fetch
-```
-
-## OpenTelemetry / OTLP path (NEW in 2.4.0)
-
-Already running OTel? Skip the Trodo SDK install entirely and point your existing pipeline at Trodo. Two env vars:
-
-```bash
-# .env.local
-OTEL_EXPORTER_OTLP_ENDPOINT=https://sdkapi.trodo.ai
-OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ${TRODO_SITE_ID}
-```
-
-The Bearer token is your **site_id** — same value you'd pass to `trodo.init({ siteId })`. Get it from the [Integration Manager](https://app.trodo.ai/dashboard/integrations).
-
-Use this when:
-- **NextJS + Vercel AI SDK with `@vercel/otel`** — auto-instrumented `generateText` / `streamText` / tool calls flow into Trodo. Pass `experimental_telemetry.metadata.{userId, sessionId, agentName, ...}` and they map to `distinct_id` / `conversation_id` / `agent_name` / custom `run.metadata`.
-- **You already run OTel** (Datadog, Jaeger, Honeycomb) and want Trodo as an additional destination. Install `trodo-node` and call `trodo.registerOTel({ siteId, mode: 'otlp' })` to attach our OTLP exporter without replacing your existing setup. `wrapAgent` / `withSpan` / `tool` then route through OTel so auto-instrumented children share the same trace.
-
-```typescript
-// instrumentation.ts (NextJS root or src/)
-import { registerOTel } from 'trodo-node';
-
-registerOTel({
-  siteId: process.env.TRODO_SITE_ID!,
-  mode: 'otlp',
-});
-```
-
-`mode: 'otlp'` requires these optional peer deps:
-
-```bash
-npm install @opentelemetry/api @opentelemetry/sdk-node \
-  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto \
-  @opentelemetry/resources
-```
-
-The SDK throws a friendly install hint if you call `mode: 'otlp'` without them.
-
-For richer Trodo features on top (`wrapAgent`, `feedback`, `trackMcp`), continue with the SDK quick start below.
-
-## Quick Start
-
-```javascript
-const trodo = require('trodo-node');
-
-trodo.init({ siteId: 'your-site-id' });
-
-// User-bound context (recommended)
-const user = trodo.forUser('user-123');
-await user.track('purchase_completed', { amount: 99.99, plan: 'pro' });
-await user.people.set({ plan: 'pro', company: 'Acme' });
-
-// Flush before process exit if using batching
-await trodo.shutdown();
-```
-
-```javascript
-// ESM
-import trodo from 'trodo-node';
-trodo.init({ siteId: 'your-site-id' });
-```
-
-## Core API
-
-### `trodo.init(config)`
-
-Call once at app startup.
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `siteId` | required | Your Trodo site ID |
-| `apiBase` | `https://sdkapi.trodo.ai` | API base URL |
-| `timeout` | `10000` ms | HTTP request timeout |
-| `retries` | `2` | Retries on network/5xx errors |
-| `autoEvents` | `false` | Hook `uncaughtException` / `unhandledRejection` as `server_error` events |
-| `batchEnabled` | `false` | Queue events and flush in batches |
-| `batchSize` | `50` | Flush when this many events are queued |
-| `batchFlushIntervalMs` | `5000` | Also flush every N milliseconds |
-| `onError` | — | Callback for SDK errors (silent by default) |
-| `debug` | `false` | Log API calls to stderr |
-
-### `trodo.forUser(distinctId, options?)`
-
-Returns a user-bound context. No API call is made until you track an event.
-
-```javascript
-const user = trodo.forUser('user-123', {
-  sessionId: req.cookies.trodo_session,  // optional: correlate with browser session
-});
-```
-
-### `trodo.identify(identifyId, options?)`
-
-Creates the session and fires `POST /api/sdk/identify`. Use to link a `distinctId` to an external identifier (email, DB id). Returns the user context.
-
-```javascript
-const user = await trodo.identify('user@example.com', {
-  sessionId: req.cookies.trodo_session,
-});
-// distinctId is now id_user@example.com — merges with browser events
-await user.track('login');
-```
-
-### User context methods
-
-```javascript
-await user.track(eventName, properties?)          // Custom event
-await user.identify(identifyId)                   // Merge identity
-await user.walletAddress(address)                 // Set wallet address
-await user.reset()                                // Clear session
-await user.captureError(err, severity?)           // Track server_error ('critical' | 'error' | 'warning')
-
-// People profile
-await user.people.set(properties)
-await user.people.setOnce(properties)
-await user.people.unset(keys)
-await user.people.increment(key, amount?)
-await user.people.append(key, values)
-await user.people.union(key, values)
-await user.people.remove(key, values)
-await user.people.trackCharge(amount, properties?)
-await user.people.clearCharges()
-await user.people.deleteUser()
-
-// Groups
-await user.set_group(groupKey, groupId)
-await user.add_group(groupKey, groupId)
-await user.remove_group(groupKey, groupId)
-const group = user.get_group(groupKey, groupId)
-await group.set(properties)
-await group.set_once(properties)
-await group.increment(key, amount?)
-await group.append(key, values)
-await group.union(key, values)
-await group.remove(key, values)
-await group.unset(keys)
-await group.delete()
-```
-
-### Direct call pattern
-
-```javascript
-await trodo.track('user-123', 'event_name', { key: 'value' })
-await trodo.people.set('user-123', { plan: 'pro' })
-await trodo.set_group('user-123', 'company', 'acme')
-```
-
----
-
-## AI Agent Tracing (recommended)
-
-One wrap around your agent captures every LLM call, tool call, and
-nested step as a tree of spans — token counts, costs, inputs, outputs,
-errors. Works with any stack: OpenAI, Anthropic, LangChain, Vercel AI
-SDK, raw HTTP, custom tools. Cost is derived server-side from
-`(provider, model)` — the SDK only sends tokens.
-
-### 30-second quickstart
-
-```typescript
-import trodo from 'trodo-node';
-trodo.init({ siteId: 'your-site-id' });   // autoInstrument on by default
-
-const { result, runId } = await trodo.wrapAgent(
-  'customer-support',
-  async (run) => {
-    run.setInput({ query });
-    const answer = await agent.run(query);  // OpenAI/Anthropic/LangChain auto-captured
-    run.setOutput(answer);
-    return answer;
-  },
-  { distinctId: userId, conversationId: sessionId },
-);
-```
-
-Open the Agent Runs dashboard — the row shows tokens in/out, cost,
-span count, tool count, error count, plus the full trace tree.
-
-### Auto-instrumentation
-
-`trodo.init()` calls `enableAutoInstrument()` which registers every
-installed OpenTelemetry instrumentor — no extra wiring.
-
-| Framework | Install |
-|-----------|---------|
-| OpenAI | `npm i @opentelemetry/instrumentation-openai` |
-| Anthropic | `npm i @opentelemetry/instrumentation-anthropic` |
-| LangChain | `npm i @opentelemetry/instrumentation-langchain` |
-| LlamaIndex | `npm i @opentelemetry/instrumentation-llamaindex` |
-| Google Gemini | `npm i @opentelemetry/instrumentation-google-generativeai` |
-| Vertex AI | `npm i @opentelemetry/instrumentation-vertexai` |
-| Bedrock | `npm i @opentelemetry/instrumentation-bedrock` |
-| Cohere | `npm i @opentelemetry/instrumentation-cohere` |
-| Vercel AI SDK | emits OTel via `experimental_telemetry: { isEnabled: true }` |
-| http / fetch | bundled — generic HTTP spans for raw-HTTP callers |
-
-Opt out with `trodo.init({ siteId, autoInstrument: false })`.
-
-### Span helpers
-
-Typed function wrappers for custom code — every call becomes a span
-with args auto-captured as `input`, return value as `output`,
-exception as `error`.
-
-```typescript
-// trace — generic span
-const prepared = trodo.trace('prepare', async (payload) => normalize(payload));
-await prepared({ raw: true });
-
-// tool — tool span (name-first OR fn-first)
-const runFunnel = trodo.tool('run_funnel_query', async (teamId, preset) => {
-  return await db.funnel(teamId, preset);
-});
-await runFunnel(1, 'day7');
-
-// llm — LLM span, auto-extracts OpenAI / Anthropic / Gemini usage
-const answer = trodo.llm('answer', async (messages) => callOpenAI(messages), {
-  model: 'gpt-4o-mini',
-  provider: 'openai',
-});
-await answer([{ role: 'user', content: 'ping' }]);
-// Records inputTokens / outputTokens from response.usage.
-
-// retrieval — vector search / RAG retriever span
-const search = trodo.retrieval('vector_search', async (q) => vecDb.query(q));
-const docs = await search('users dropping off');
-```
-
-### Raw-HTTP escape hatches
-
-If your LLM client isn't OTel-instrumented and you can't wrap it as a
-function, record a span post-hoc:
-
-```typescript
-const resp = await fetch(url, { body: JSON.stringify(body) }).then(r => r.json());
-await trodo.trackLlmCall({
-  model: 'gemini-2.5-flash',
-  provider: 'google',
-  inputTokens: resp.usageMetadata.promptTokenCount,
-  outputTokens: resp.usageMetadata.candidatesTokenCount,
-  prompt: body,
-  completion: resp,
-});
-```
-
-For advanced cases, get a raw OTel tracer — the Trodo processor is
-already subscribed:
-
-```typescript
-const tracer = trodo.getTracer('my.module');
-tracer.startActiveSpan('custom', (span) => {
-  span.setAttribute('gen_ai.system', 'my-llm');
-  span.end();
-});
-```
-
-### Cross-service runs
-
-When one service calls another, the downstream service **joins** the
-caller's run instead of creating its own — all spans nest under a
-single timeline.
-
-```typescript
-// Caller — outbound:
-await fetch(url, {
-  method: 'POST',
-  headers: { ...trodo.propagationHeaders(), 'content-type': 'application/json' },
-  body: JSON.stringify(payload),
-});
-
-// Downstream (Express):
-import express from 'express';
-const app = express();
-app.use(trodo.expressMiddleware());
-// Every LLM call / tool / trace helper inside handlers now nests under
-// the caller's run.
-
-// Or manually:
-await trodo.joinRun(
-  req.headers['x-trodo-run-id'] as string,
-  req.headers['x-trodo-parent-span-id'] as string,
-  async () => { /* ... */ },
-);
-```
-
-### Long-lived sessions across processes — `startRun` / `endRun`
-
-`wrapAgent` is a single-callback block — it opens *and* closes the run in
-one function call. For sessions that live across many HTTP requests (an
-MCP server, a websocket-pinned chat, scheduled jobs that resume on
-different workers), use `startRun` to open the run from one process and
-`endRun` to finalise it later. Between the two, any process can use
-`joinRun` to add child spans. Same `runId` threads through everything.
-
-```typescript
-// Process A — open the run for an MCP session.
-const runId = await trodo.startRun('external_mcp_session', {
-  distinctId: String(userId),
-  conversationId: mcpSessionId,
-});
-await redis.set(`mcp:run:${mcpSessionId}`, runId, 'EX', 3600);
-
-// Process B (later, possibly a different worker) — append a tool span.
-const runId = await redis.get(`mcp:run:${mcpSessionId}`);
-await trodo.joinRun(runId, null, async (span) => {
-  span.setInput(args);
-  span.setOutput(result);
-}, { name: 'tool.run_funnel_query', kind: 'tool' });
-
-// When the session ends (timeout sweeper, explicit close):
-await trodo.endRun(runId, { status: 'ok' });
-```
-
-### Conversation binding & feedback
-
-```typescript
-const { runId } = await trodo.wrapAgent(
-  'chat',
-  async (run) => { /* ... */ },
-  { distinctId: userId, conversationId: sessionId },
-);
-await trodo.feedback(runId, { satisfaction: 'positive', rating: 5 });
-```
-
----
-
-## Agent Analytics (legacy event-based API)
-
-The older per-event API below is still supported but superseded by
-`wrapAgent` + span helpers above. Use it only if you're already wired
-into it; new integrations should prefer the tracing API.
-
-**Before you start:** register your agent in **Integrations → AI Agents** in the dashboard to get an `agent_id` (`agt_xxxxxxxx`).
-
-### `track_agent_call` — inbound message / LLM invocation
-
-```javascript
-await trodo.track_agent_call({
-  agentId: 'agt_abc12345',
-  conversationId: 'conv_xyz',
-  messageId: 'msg_001',
-  prompt: userMessage,
-  model: 'gpt-4o',
-  provider: 'openai',
-  systemPromptVersion: 'v2',   // optional — track prompt iterations
-  distinctId: userId,           // optional — link to a Trodo user
-  metadata: { threadSource: 'slack', locale: 'en' }, // optional — stored in agent_calls.metadata (JSONB)
-});
-```
-
-### `track_tool_use` — tool/function call within a turn
-
-```javascript
-await trodo.track_tool_use({
-  agentId: 'agt_abc12345',
-  conversationId: 'conv_xyz',
-  messageId: 'msg_001',
-  toolName: 'fetch_billing_info',
-  latencyMs: 143,
-  status: 'success',            // 'success' | 'failure'
-  input: { userId: '123' },     // optional
-  output: { plan: 'pro' },      // optional
-});
-```
-
-### `track_agent_response` — LLM output and token usage
-
-```javascript
-await trodo.track_agent_response({
-  agentId: 'agt_abc12345',
-  conversationId: 'conv_xyz',
-  messageId: 'msg_001',
-  model: 'gpt-4o',
-  completionTokens: response.usage.completion_tokens,
-  promptTokens: response.usage.prompt_tokens,
-  totalTokens: response.usage.total_tokens,
-  finishReason: response.choices[0].finish_reason,
-  distinctId: userId,
-});
-```
-
-### `track_agent_error` — errors and failures
-
-```javascript
-await trodo.track_agent_error({
-  agentId: 'agt_abc12345',
-  conversationId: 'conv_xyz',
-  messageId: 'msg_001',
-  errorType: 'rate_limit',       // 'timeout' | 'rate_limit' | 'guardrail_block' | ...
-  errorMessage: err.message,
-  failedTool: 'fetch_billing_info',  // optional
-});
-```
-
-### `track_feedback` — user thumbs up/down
-
-```javascript
-await trodo.track_feedback({
-  agentId: 'agt_abc12345',
-  conversationId: 'conv_xyz',
-  messageId: 'msg_001',          // same messageId as the response it refers to
-  feedback: 'positive',          // 'positive' | 'negative' | 'unreact'
-  distinctId: userId,
-});
-```
-
-### Full turn example
-
-```javascript
-async function runAgentTurn(userId, conversationId, userMessage) {
-  const agentId = 'agt_abc12345';
-  const messageId = `msg_${Date.now()}`;
-
-  await trodo.track_agent_call({ agentId, conversationId, messageId, prompt: userMessage, distinctId: userId });
-
-  try {
-    await trodo.track_tool_use({ agentId, conversationId, messageId, toolName: 'search', status: 'success', latencyMs: 80 });
-
-    const response = await llm.complete(userMessage);
-
-    await trodo.track_agent_response({
-      agentId, conversationId, messageId,
-      model: response.model,
-      completionTokens: response.usage.completion_tokens,
-      promptTokens: response.usage.prompt_tokens,
-      totalTokens: response.usage.total_tokens,
-      distinctId: userId,
-    });
-
-    return response.text;
-  } catch (err) {
-    await trodo.track_agent_error({ agentId, conversationId, messageId, errorType: err.type, errorMessage: err.message, distinctId: userId });
-    throw err;
-  }
-}
-```
-
----
-
-## Identity Merging (Cross-SDK)
-
-Call `identify()` with the **same value** on the browser and server to merge all events under one user profile:
-
-```javascript
-// Browser
-Trodo.identify('user@example.com');   // → id_user@example.com
-
-// Node.js (same value)
-await user.identify('user@example.com');  // → id_user@example.com
-// Events from both sides now appear together in the dashboard
-```
-
----
-
-## Batching
-
-```javascript
-trodo.init({
-  siteId: 'your-site-id',
-  batchEnabled: true,
-  batchSize: 50,
-  batchFlushIntervalMs: 5000,
-});
-
-// Always flush before process exit
-process.on('SIGTERM', async () => { await trodo.shutdown(); process.exit(0); });
-```
-
----
-
-## Auto Events
-
-```javascript
-trodo.init({ siteId: 'your-site-id', autoEvents: true });
-// Hooks process.on('uncaughtException') and process.on('unhandledRejection')
-// Sends server_error events with distinct_id: 'server_global'
-
-// Toggle at runtime
-trodo.enableAutoEvents();
-trodo.disableAutoEvents();
-```
-
----
-
-## TypeScript
-
-Full type declarations bundled:
-
-```typescript
-import trodo, { TrodoClient, UserContext } from 'trodo-node';
-import type { AgentCallProps, ToolUseProps, AgentResponseProps, AgentErrorProps, FeedbackProps } from 'trodo-node';
-
-// Multi-tenant
-const client = new TrodoClient({ siteId: 'your-site-id' });
-```
-
-## License
-
-ISC
+# trodo-node
+
+Server-side Node.js SDK for [Trodo Analytics](https://trodo.ai). Track backend events, identify users, manage people/groups, and instrument AI agents — all unified with your frontend data under the same `siteId`.
+
+## Installation
+
+```bash
+npm install trodo-node
+```
+
+Node 18+ uses native `fetch`. For Node 16/17, install the optional peer dependency:
+
+```bash
+npm install trodo-node node-fetch
+```
+
+## OpenTelemetry / OTLP path (NEW in 2.4.0)
+
+Already running OTel? Skip the Trodo SDK install entirely and point your existing pipeline at Trodo. Two env vars:
+
+```bash
+# .env.local
+OTEL_EXPORTER_OTLP_ENDPOINT=https://sdkapi.trodo.ai
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer ${TRODO_SITE_ID}
+```
+
+The Bearer token is your **site_id** — same value you'd pass to `trodo.init({ siteId })`. Get it from the [Integration Manager](https://app.trodo.ai/dashboard/integrations).
+
+Use this when:
+- **NextJS + Vercel AI SDK with `@vercel/otel`** — auto-instrumented `generateText` / `streamText` / tool calls flow into Trodo. Pass `experimental_telemetry.metadata.{userId, sessionId, agentName, ...}` and they map to `distinct_id` / `conversation_id` / `agent_name` / custom `run.metadata`.
+- **You already run OTel** (Datadog, Jaeger, Honeycomb) and want Trodo as an additional destination. Install `trodo-node` and call `trodo.registerOTel({ siteId, mode: 'otlp' })` to attach our OTLP exporter without replacing your existing setup. `wrapAgent` / `withSpan` / `tool` then route through OTel so auto-instrumented children share the same trace.
+
+```typescript
+// instrumentation.ts (NextJS root or src/)
+import { registerOTel } from 'trodo-node';
+
+registerOTel({
+  siteId: process.env.TRODO_SITE_ID!,
+  mode: 'otlp',
+});
+```
+
+`mode: 'otlp'` requires these optional peer deps:
+
+```bash
+npm install @opentelemetry/api @opentelemetry/sdk-node \
+  @opentelemetry/sdk-trace-base @opentelemetry/exporter-trace-otlp-proto \
+  @opentelemetry/resources
+```
+
+The SDK throws a friendly install hint if you call `mode: 'otlp'` without them.
+
+For richer Trodo features on top (`wrapAgent`, `feedback`, `trackMcp`), continue with the SDK quick start below.
+
+## Quick Start
+
+```javascript
+const trodo = require('trodo-node');
+
+trodo.init({ siteId: 'your-site-id' });
+
+// User-bound context (recommended)
+const user = trodo.forUser('user-123');
+await user.track('purchase_completed', { amount: 99.99, plan: 'pro' });
+await user.people.set({ plan: 'pro', company: 'Acme' });
+
+// Flush before process exit if using batching
+await trodo.shutdown();
+```
+
+```javascript
+// ESM
+import trodo from 'trodo-node';
+trodo.init({ siteId: 'your-site-id' });
+```
+
+## Core API
+
+### `trodo.init(config)`
+
+Call once at app startup.
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `siteId` | required | Your Trodo site ID |
+| `apiBase` | `https://sdkapi.trodo.ai` | API base URL |
+| `timeout` | `10000` ms | HTTP request timeout |
+| `retries` | `2` | Retries on network/5xx errors |
+| `autoEvents` | `false` | Hook `uncaughtException` / `unhandledRejection` as `server_error` events |
+| `batchEnabled` | `false` | Queue events and flush in batches |
+| `batchSize` | `50` | Flush when this many events are queued |
+| `batchFlushIntervalMs` | `5000` | Also flush every N milliseconds |
+| `onError` | — | Callback for SDK errors (silent by default) |
+| `debug` | `false` | Log API calls to stderr |
+
+### `trodo.forUser(distinctId, options?)`
+
+Returns a user-bound context. No API call is made until you track an event.
+
+```javascript
+const user = trodo.forUser('user-123', {
+  sessionId: req.cookies.trodo_session,  // optional: correlate with browser session
+});
+```
+
+### `trodo.identify(identifyId, options?)`
+
+Creates the session and fires `POST /api/sdk/identify`. Use to link a `distinctId` to an external identifier (email, DB id). Returns the user context.
+
+```javascript
+const user = await trodo.identify('user@example.com', {
+  sessionId: req.cookies.trodo_session,
+});
+// distinctId is now id_user@example.com — merges with browser events
+await user.track('login');
+```
+
+### User context methods
+
+```javascript
+await user.track(eventName, properties?)          // Custom event
+await user.identify(identifyId)                   // Merge identity
+await user.walletAddress(address)                 // Set wallet address
+await user.reset()                                // Clear session
+await user.captureError(err, severity?)           // Track server_error ('critical' | 'error' | 'warning')
+
+// People profile
+await user.people.set(properties)
+await user.people.setOnce(properties)
+await user.people.unset(keys)
+await user.people.increment(key, amount?)
+await user.people.append(key, values)
+await user.people.union(key, values)
+await user.people.remove(key, values)
+await user.people.trackCharge(amount, properties?)
+await user.people.clearCharges()
+await user.people.deleteUser()
+
+// Groups
+await user.set_group(groupKey, groupId)
+await user.add_group(groupKey, groupId)
+await user.remove_group(groupKey, groupId)
+const group = user.get_group(groupKey, groupId)
+await group.set(properties)
+await group.set_once(properties)
+await group.increment(key, amount?)
+await group.append(key, values)
+await group.union(key, values)
+await group.remove(key, values)
+await group.unset(keys)
+await group.delete()
+```
+
+### Direct call pattern
+
+```javascript
+await trodo.track('user-123', 'event_name', { key: 'value' })
+await trodo.people.set('user-123', { plan: 'pro' })
+await trodo.set_group('user-123', 'company', 'acme')
+```
+
+---
+
+## AI Agent Tracing (recommended)
+
+One wrap around your agent captures every LLM call, tool call, and
+nested step as a tree of spans — token counts, costs, inputs, outputs,
+errors. Works with any stack: OpenAI, Anthropic, LangChain, Vercel AI
+SDK, raw HTTP, custom tools. Cost is derived server-side from
+`(provider, model)` — the SDK only sends tokens.
+
+### 30-second quickstart
+
+```typescript
+import trodo from 'trodo-node';
+trodo.init({ siteId: 'your-site-id' });   // autoInstrument on by default
+
+const { result, runId } = await trodo.wrapAgent(
+  'customer-support',
+  async (run) => {
+    run.setInput({ query });
+    const answer = await agent.run(query);  // OpenAI/Anthropic/LangChain auto-captured
+    run.setOutput(answer);
+    return answer;
+  },
+  { distinctId: userId, conversationId: sessionId },
+);
+```
+
+Open the Agent Runs dashboard — the row shows tokens in/out, cost,
+span count, tool count, error count, plus the full trace tree.
+
+### Auto-instrumentation
+
+`trodo.init()` calls `enableAutoInstrument()` which registers every
+installed OpenTelemetry instrumentor — no extra wiring.
+
+| Framework | Install |
+|-----------|---------|
+| OpenAI | `npm i @opentelemetry/instrumentation-openai` |
+| Anthropic | `npm i @opentelemetry/instrumentation-anthropic` |
+| LangChain | `npm i @opentelemetry/instrumentation-langchain` |
+| LlamaIndex | `npm i @opentelemetry/instrumentation-llamaindex` |
+| Google Gemini | `npm i @opentelemetry/instrumentation-google-generativeai` |
+| Vertex AI | `npm i @opentelemetry/instrumentation-vertexai` |
+| Bedrock | `npm i @opentelemetry/instrumentation-bedrock` |
+| Cohere | `npm i @opentelemetry/instrumentation-cohere` |
+| Vercel AI SDK | emits OTel via `experimental_telemetry: { isEnabled: true }` |
+| http / fetch | bundled — generic HTTP spans for raw-HTTP callers |
+
+Opt out with `trodo.init({ siteId, autoInstrument: false })`.
+
+### Span helpers
+
+Typed function wrappers for custom code — every call becomes a span
+with args auto-captured as `input`, return value as `output`,
+exception as `error`.
+
+```typescript
+// trace — generic span
+const prepared = trodo.trace('prepare', async (payload) => normalize(payload));
+await prepared({ raw: true });
+
+// tool — tool span (name-first OR fn-first)
+const runFunnel = trodo.tool('run_funnel_query', async (teamId, preset) => {
+  return await db.funnel(teamId, preset);
+});
+await runFunnel(1, 'day7');
+
+// llm — LLM span, auto-extracts OpenAI / Anthropic / Gemini usage
+const answer = trodo.llm('answer', async (messages) => callOpenAI(messages), {
+  model: 'gpt-4o-mini',
+  provider: 'openai',
+});
+await answer([{ role: 'user', content: 'ping' }]);
+// Records inputTokens / outputTokens from response.usage.
+
+// retrieval — vector search / RAG retriever span
+const search = trodo.retrieval('vector_search', async (q) => vecDb.query(q));
+const docs = await search('users dropping off');
+```
+
+### Raw-HTTP escape hatches
+
+If your LLM client isn't OTel-instrumented and you can't wrap it as a
+function, record a span post-hoc:
+
+```typescript
+const resp = await fetch(url, { body: JSON.stringify(body) }).then(r => r.json());
+await trodo.trackLlmCall({
+  model: 'gemini-2.5-flash',
+  provider: 'google',
+  inputTokens: resp.usageMetadata.promptTokenCount,
+  outputTokens: resp.usageMetadata.candidatesTokenCount,
+  prompt: body,
+  completion: resp,
+});
+```
+
+For advanced cases, get a raw OTel tracer — the Trodo processor is
+already subscribed:
+
+```typescript
+const tracer = trodo.getTracer('my.module');
+tracer.startActiveSpan('custom', (span) => {
+  span.setAttribute('gen_ai.system', 'my-llm');
+  span.end();
+});
+```
+
+### Cross-service runs
+
+When one service calls another, the downstream service **joins** the
+caller's run instead of creating its own — all spans nest under a
+single timeline.
+
+```typescript
+// Caller — outbound:
+await fetch(url, {
+  method: 'POST',
+  headers: { ...trodo.propagationHeaders(), 'content-type': 'application/json' },
+  body: JSON.stringify(payload),
+});
+
+// Downstream (Express):
+import express from 'express';
+const app = express();
+app.use(trodo.expressMiddleware());
+// Every LLM call / tool / trace helper inside handlers now nests under
+// the caller's run.
+
+// Or manually:
+await trodo.joinRun(
+  req.headers['x-trodo-run-id'] as string,
+  req.headers['x-trodo-parent-span-id'] as string,
+  async () => { /* ... */ },
+);
+```
+
+### Long-lived sessions across processes — `startRun` / `endRun`
+
+`wrapAgent` is a single-callback block — it opens *and* closes the run in
+one function call. For sessions that live across many HTTP requests (an
+MCP server, a websocket-pinned chat, scheduled jobs that resume on
+different workers), use `startRun` to open the run from one process and
+`endRun` to finalise it later. Between the two, any process can use
+`joinRun` to add child spans. Same `runId` threads through everything.
+
+```typescript
+// Process A — open the run for an MCP session.
+const runId = await trodo.startRun('external_mcp_session', {
+  distinctId: String(userId),
+  conversationId: mcpSessionId,
+});
+await redis.set(`mcp:run:${mcpSessionId}`, runId, 'EX', 3600);
+
+// Process B (later, possibly a different worker) — append a tool span.
+const runId = await redis.get(`mcp:run:${mcpSessionId}`);
+await trodo.joinRun(runId, null, async (span) => {
+  span.setInput(args);
+  span.setOutput(result);
+}, { name: 'tool.run_funnel_query', kind: 'tool' });
+
+// When the session ends (timeout sweeper, explicit close):
+await trodo.endRun(runId, { status: 'ok' });
+```
+
+### Conversation binding & feedback
+
+```typescript
+const { runId } = await trodo.wrapAgent(
+  'chat',
+  async (run) => { /* ... */ },
+  { distinctId: userId, conversationId: sessionId },
+);
+await trodo.feedback(runId, { satisfaction: 'positive', rating: 5 });
+```
+
+---
+
+## Agent Analytics (legacy event-based API)
+
+The older per-event API below is still supported but superseded by
+`wrapAgent` + span helpers above. Use it only if you're already wired
+into it; new integrations should prefer the tracing API.
+
+**Before you start:** register your agent in **Integrations → AI Agents** in the dashboard to get an `agent_id` (`agt_xxxxxxxx`).
+
+### `track_agent_call` — inbound message / LLM invocation
+
+```javascript
+await trodo.track_agent_call({
+  agentId: 'agt_abc12345',
+  conversationId: 'conv_xyz',
+  messageId: 'msg_001',
+  prompt: userMessage,
+  model: 'gpt-4o',
+  provider: 'openai',
+  systemPromptVersion: 'v2',   // optional — track prompt iterations
+  distinctId: userId,           // optional — link to a Trodo user
+  metadata: { threadSource: 'slack', locale: 'en' }, // optional — stored in agent_calls.metadata (JSONB)
+});
+```
+
+### `track_tool_use` — tool/function call within a turn
+
+```javascript
+await trodo.track_tool_use({
+  agentId: 'agt_abc12345',
+  conversationId: 'conv_xyz',
+  messageId: 'msg_001',
+  toolName: 'fetch_billing_info',
+  latencyMs: 143,
+  status: 'success',            // 'success' | 'failure'
+  input: { userId: '123' },     // optional
+  output: { plan: 'pro' },      // optional
+});
+```
+
+### `track_agent_response` — LLM output and token usage
+
+```javascript
+await trodo.track_agent_response({
+  agentId: 'agt_abc12345',
+  conversationId: 'conv_xyz',
+  messageId: 'msg_001',
+  model: 'gpt-4o',
+  completionTokens: response.usage.completion_tokens,
+  promptTokens: response.usage.prompt_tokens,
+  totalTokens: response.usage.total_tokens,
+  finishReason: response.choices[0].finish_reason,
+  distinctId: userId,
+});
+```
+
+### `track_agent_error` — errors and failures
+
+```javascript
+await trodo.track_agent_error({
+  agentId: 'agt_abc12345',
+  conversationId: 'conv_xyz',
+  messageId: 'msg_001',
+  errorType: 'rate_limit',       // 'timeout' | 'rate_limit' | 'guardrail_block' | ...
+  errorMessage: err.message,
+  failedTool: 'fetch_billing_info',  // optional
+});
+```
+
+### `track_feedback` — user thumbs up/down
+
+```javascript
+await trodo.track_feedback({
+  agentId: 'agt_abc12345',
+  conversationId: 'conv_xyz',
+  messageId: 'msg_001',          // same messageId as the response it refers to
+  feedback: 'positive',          // 'positive' | 'negative' | 'unreact'
+  distinctId: userId,
+});
+```
+
+### Full turn example
+
+```javascript
+async function runAgentTurn(userId, conversationId, userMessage) {
+  const agentId = 'agt_abc12345';
+  const messageId = `msg_${Date.now()}`;
+
+  await trodo.track_agent_call({ agentId, conversationId, messageId, prompt: userMessage, distinctId: userId });
+
+  try {
+    await trodo.track_tool_use({ agentId, conversationId, messageId, toolName: 'search', status: 'success', latencyMs: 80 });
+
+    const response = await llm.complete(userMessage);
+
+    await trodo.track_agent_response({
+      agentId, conversationId, messageId,
+      model: response.model,
+      completionTokens: response.usage.completion_tokens,
+      promptTokens: response.usage.prompt_tokens,
+      totalTokens: response.usage.total_tokens,
+      distinctId: userId,
+    });
+
+    return response.text;
+  } catch (err) {
+    await trodo.track_agent_error({ agentId, conversationId, messageId, errorType: err.type, errorMessage: err.message, distinctId: userId });
+    throw err;
+  }
+}
+```
+
+---
+
+## Identity Merging (Cross-SDK)
+
+Call `identify()` with the **same value** on the browser and server to merge all events under one user profile:
+
+```javascript
+// Browser
+Trodo.identify('user@example.com');   // → id_user@example.com
+
+// Node.js (same value)
+await user.identify('user@example.com');  // → id_user@example.com
+// Events from both sides now appear together in the dashboard
+```
+
+---
+
+## Batching
+
+```javascript
+trodo.init({
+  siteId: 'your-site-id',
+  batchEnabled: true,
+  batchSize: 50,
+  batchFlushIntervalMs: 5000,
+});
+
+// Always flush before process exit
+process.on('SIGTERM', async () => { await trodo.shutdown(); process.exit(0); });
+```
+
+---
+
+## Auto Events
+
+```javascript
+trodo.init({ siteId: 'your-site-id', autoEvents: true });
+// Hooks process.on('uncaughtException') and process.on('unhandledRejection')
+// Sends server_error events with distinct_id: 'server_global'
+
+// Toggle at runtime
+trodo.enableAutoEvents();
+trodo.disableAutoEvents();
+```
+
+---
+
+## TypeScript
+
+Full type declarations bundled:
+
+```typescript
+import trodo, { TrodoClient, UserContext } from 'trodo-node';
+import type { AgentCallProps, ToolUseProps, AgentResponseProps, AgentErrorProps, FeedbackProps } from 'trodo-node';
+
+// Multi-tenant
+const client = new TrodoClient({ siteId: 'your-site-id' });
+```
+
+## License
+
+ISC