{"_id":"@ambertrace/node","name":"@ambertrace/node","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@ambertrace/node","version":"0.1.0","description":"TypeScript/Node.js SDK for tracing LLM calls (OpenAI, Anthropic, Google Gemini) to AmberTrace observability platform","type":"module","main":"./dist/cjs/index.js","module":"./dist/esm/index.js","types":"./dist/types/index.d.ts","exports":{".":{"import":"./dist/esm/index.js","require":"./dist/cjs/index.js","types":"./dist/types/index.d.ts"}},"scripts":{"build":"npm run build:esm && npm run build:cjs && npm run build:types","build:esm":"tsc -p tsconfig.build.json --module esnext --outDir dist/esm","build:cjs":"tsc -p tsconfig.build.json --module commonjs --outDir dist/cjs","build:types":"tsc -p tsconfig.build.json --declaration --emitDeclarationOnly --outDir dist/types","clean":"rm -rf dist","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","lint":"eslint src/**/*.ts","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","test:backend":"tsx scripts/test-real-backend.ts","prepublishOnly":"npm run clean && npm run build"},"keywords":["llm","observability","tracing","openai","anthropic","claude","gpt","gemini","google","monitoring","typescript","nodejs"],"author":{"name":"AmberTrace","email":"hello@ambertrace.dev"},"license":"Apache-2.0","repository":{"type":"git","url":"git+https://github.com/ambertrace/ambertrace-sdk.git","directory":"typescript"},"bugs":{"url":"https://github.com/ambertrace/ambertrace-sdk/issues"},"homepage":"https://github.com/ambertrace/ambertrace-sdk#readme","dependencies":{"node-fetch":"^3.3.0","tslib":"^2.8.1"},"peerDependencies":{"@anthropic-ai/sdk":">=0.18.0","@google/genai":">=0.1.0","@google/generative-ai":">=0.1.0","openai":">=4.0.0"},"peerDependenciesMeta":{"openai":{"optional":true},"@anthropic-ai/sdk":{"optional":true},"@google/generative-ai":{"optional":true},"@google/genai":{"optional":true}},"devDependencies":{"@anthropic-ai/sdk":"^0.18.0","@google/generative-ai":"^0.21.0","@types/jest":"^29.5.0","@types/node":"^20.0.0","@typescript-eslint/eslint-plugin":"^6.0.0","@typescript-eslint/parser":"^6.0.0","eslint":"^8.50.0","jest":"^29.7.0","openai":"^4.0.0","prettier":"^3.0.0","ts-jest":"^29.1.0","tsx":"^4.0.0","typescript":"^5.2.0"},"engines":{"node":">=16.0.0"},"_id":"@ambertrace/node@0.1.0","gitHead":"6fd8626b760b320eca018d6cd44bf30c63795414","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-Xb5rxBD9ZoJT4XZxFd4sRDERJa6bCchcNYmZ0RN/D0/dlAx54SVpyhxGQQXxkCdC+OXkPAdX31O5/tDZ7Vj+Ew==","shasum":"f9b6750982321c4cec77df477d83f0a42658de15","tarball":"https://registry.npmjs.org/@ambertrace/node/-/node-0.1.0.tgz","fileCount":67,"unpackedSize":124383,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCmaEfKrFsCVtLRp3+S4LH0m2u2r0t63u/cqLNgU6Fc6AIhANE1InsAHeFlcHbZLr5b0y9UEsPYI3YRJG2Z3li0BHuQ"}]},"_npmUser":{"name":"kirpros","email":"kirpros88@gmail.com"},"directories":{},"maintainers":[{"name":"kirpros","email":"kirpros88@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/node_0.1.0_1770820773930_0.3647659144849844"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-11T14:39:33.858Z","0.1.0":"2026-02-11T14:39:34.089Z","modified":"2026-02-11T14:39:34.358Z"},"maintainers":[{"name":"kirpros","email":"kirpros88@gmail.com"}],"description":"TypeScript/Node.js SDK for tracing LLM calls (OpenAI, Anthropic, Google Gemini) to AmberTrace observability platform","homepage":"https://github.com/ambertrace/ambertrace-sdk#readme","keywords":["llm","observability","tracing","openai","anthropic","claude","gpt","gemini","google","monitoring","typescript","nodejs"],"repository":{"type":"git","url":"git+https://github.com/ambertrace/ambertrace-sdk.git","directory":"typescript"},"author":{"name":"AmberTrace","email":"hello@ambertrace.dev"},"bugs":{"url":"https://github.com/ambertrace/ambertrace-sdk/issues"},"license":"Apache-2.0","readme":"# AmberTrace TypeScript/Node.js SDK\n\nOfficial TypeScript/Node.js SDK for tracing LLM calls (OpenAI, Anthropic, Google Gemini) to the AmberTrace observability platform.\n\n## Features\n\n- **Zero-code integration** - Just call `init()` and your LLM calls are automatically traced\n- **Multi-provider support** - Works with OpenAI, Anthropic, and Google Gemini SDKs simultaneously\n- **Framework-agnostic** - Works with Express, NestJS, Next.js, and any Node.js framework\n- **Type-safe** - Full TypeScript support with complete type definitions\n- **Dual module support** - Works with both ESM and CommonJS\n- **Async-first** - Non-blocking trace delivery never impacts your application performance\n- **Silent failures** - Network issues never crash your application\n- **Auto-detection** - Automatically detects and instruments installed LLM SDKs\n\n## Installation\n\n```bash\nnpm install @ambertrace/node\n```\n\nInstall your preferred LLM SDK(s):\n\n```bash\n# For OpenAI support\nnpm install openai\n\n# For Anthropic support\nnpm install @anthropic-ai/sdk\n\n# For Google Gemini support (original SDK)\nnpm install @google/generative-ai\n\n# For Google Gemini support (newer SDK)\nnpm install @google/genai\n\n# Or all providers\nnpm install openai @anthropic-ai/sdk @google/generative-ai\n```\n\n## Quick Start\n\n```typescript\nimport ambertrace from '@ambertrace/node';\nimport OpenAI from 'openai';\n\n// 1. Initialize AmberTrace (one time, at app startup)\nambertrace.init({\n  apiKey: process.env.AMBERTRACE_API_KEY,\n  environment: 'production',\n});\n\n// 2. Use OpenAI as normal - calls are automatically traced!\nconst openai = new OpenAI({\n  apiKey: process.env.OPENAI_API_KEY,\n});\n\nconst response = await openai.chat.completions.create({\n  model: 'gpt-4',\n  messages: [{ role: 'user', content: 'Hello!' }],\n});\n\nconsole.log(response.choices[0].message.content);\n\n// 3. Before exiting, flush pending traces\nawait ambertrace.flush();\n```\n\nThat's it! Every OpenAI, Anthropic, and Gemini call is now traced to your AmberTrace dashboard.\n\n## Configuration\n\n### Initialization Options\n\n```typescript\nambertrace.init({\n  // Required: Your AmberTrace API key\n  apiKey: 'your-api-key',\n\n  // Optional: Base URL for AmberTrace API (default: https://api.ambertrace.dev)\n  baseUrl: 'https://api.ambertrace.dev',\n\n  // Optional: Environment name for filtering traces (e.g., \"production\", \"staging\")\n  environment: 'production',\n\n  // Optional: Enable debug logging (default: false)\n  debug: true,\n\n  // Optional: HTTP request timeout in ms (default: 5000)\n  timeout: 5000,\n\n  // Optional: Enable/disable tracing (default: true)\n  enabled: true,\n});\n```\n\n### Environment Variables\n\nAll configuration can be set via environment variables:\n\n```bash\nexport AMBERTRACE_API_KEY=\"your-api-key\"\nexport AMBERTRACE_BASE_URL=\"https://api.ambertrace.dev\"\nexport AMBERTRACE_ENVIRONMENT=\"production\"\nexport AMBERTRACE_DEBUG=\"true\"\nexport AMBERTRACE_TIMEOUT=\"5000\"\nexport AMBERTRACE_ENABLED=\"true\"\n```\n\n## API Reference\n\n### `init(options)`\n\nInitialize the SDK and start tracing.\n\n```typescript\nambertrace.init({\n  apiKey: 'your-api-key',\n  environment: 'production',\n});\n```\n\n### `enable()`\n\nEnable tracing (applies interception).\n\n```typescript\nambertrace.enable();\n```\n\n### `disable()`\n\nDisable tracing (removes interception).\n\n```typescript\nambertrace.disable();\n```\n\n### `isEnabled()`\n\nCheck if tracing is currently active.\n\n```typescript\nif (ambertrace.isEnabled()) {\n  console.log('Tracing is active');\n}\n```\n\n### `flush(timeoutMs?)`\n\nWait for all pending traces to be sent. Call before process exit.\n\n```typescript\nawait ambertrace.flush(10000); // Wait up to 10 seconds\n```\n\n### `shutdown(timeoutMs?)`\n\nShutdown the SDK, flush traces, and clean up resources.\n\n```typescript\nawait ambertrace.shutdown();\n```\n\n## Usage Examples\n\n### OpenAI (ESM)\n\n```typescript\nimport ambertrace from '@ambertrace/node';\nimport OpenAI from 'openai';\n\nambertrace.init({ apiKey: process.env.AMBERTRACE_API_KEY });\n\nconst openai = new OpenAI();\nconst response = await openai.chat.completions.create({\n  model: 'gpt-4',\n  messages: [{ role: 'user', content: 'Explain TypeScript' }],\n});\n\nawait ambertrace.flush();\n```\n\n### Anthropic (ESM)\n\n```typescript\nimport ambertrace from '@ambertrace/node';\nimport Anthropic from '@anthropic-ai/sdk';\n\nambertrace.init({ apiKey: process.env.AMBERTRACE_API_KEY });\n\nconst anthropic = new Anthropic();\nconst response = await anthropic.messages.create({\n  model: 'claude-opus-4-5-20251101',\n  max_tokens: 100,\n  messages: [{ role: 'user', content: 'Hello Claude!' }],\n});\n\nawait ambertrace.flush();\n```\n\n### Google Gemini (ESM)\n\nUsing the original `@google/generative-ai` SDK:\n\n```typescript\nimport ambertrace from '@ambertrace/node';\nimport { GoogleGenerativeAI } from '@google/generative-ai';\n\nambertrace.init({ apiKey: process.env.AMBERTRACE_API_KEY });\n\nconst genai = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);\nconst model = genai.getGenerativeModel({ model: 'gemini-pro' });\n\nconst result = await model.generateContent('Explain TypeScript');\nconsole.log(result.response.text());\n\nawait ambertrace.flush();\n```\n\nUsing the newer `@google/genai` SDK:\n\n```typescript\nimport ambertrace from '@ambertrace/node';\nimport { GoogleGenAI } from '@google/genai';\n\nambertrace.init({ apiKey: process.env.AMBERTRACE_API_KEY });\n\nconst ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });\nconst response = await ai.models.generateContent({\n  model: 'gemini-2.0-flash',\n  contents: 'Explain TypeScript',\n});\n\nconsole.log(response.text);\n\nawait ambertrace.flush();\n```\n\n### CommonJS\n\n```javascript\nconst ambertrace = require('@ambertrace/node').default;\nconst OpenAI = require('openai');\n\nambertrace.init({ apiKey: process.env.AMBERTRACE_API_KEY });\n\nconst openai = new OpenAI();\n// ... use OpenAI as normal\n```\n\n### Express.js API\n\n```typescript\nimport express from 'express';\nimport ambertrace from '@ambertrace/node';\nimport OpenAI from 'openai';\n\n// Initialize AmberTrace at app startup\nambertrace.init({ apiKey: process.env.AMBERTRACE_API_KEY });\n\nconst app = express();\nconst openai = new OpenAI();\n\napp.post('/chat', async (req, res) => {\n  const response = await openai.chat.completions.create({\n    model: 'gpt-4',\n    messages: [{ role: 'user', content: req.body.message }],\n  });\n\n  res.json({ reply: response.choices[0].message.content });\n});\n\napp.listen(3000);\n\n// Graceful shutdown\nprocess.on('SIGTERM', async () => {\n  await ambertrace.shutdown();\n  process.exit(0);\n});\n```\n\n### Next.js API Route\n\n```typescript\n// app/api/chat/route.ts\nimport ambertrace from '@ambertrace/node';\nimport OpenAI from 'openai';\n\n// Initialize once (consider using a singleton)\nif (!ambertrace.isEnabled()) {\n  ambertrace.init({ apiKey: process.env.AMBERTRACE_API_KEY });\n}\n\nconst openai = new OpenAI();\n\nexport async function POST(request: Request) {\n  const { message } = await request.json();\n\n  const response = await openai.chat.completions.create({\n    model: 'gpt-4',\n    messages: [{ role: 'user', content: message }],\n  });\n\n  return Response.json({ reply: response.choices[0].message.content });\n}\n```\n\n### Multi-Provider (OpenAI + Anthropic + Gemini)\n\n```typescript\nimport ambertrace from '@ambertrace/node';\nimport OpenAI from 'openai';\nimport Anthropic from '@anthropic-ai/sdk';\nimport { GoogleGenerativeAI } from '@google/generative-ai';\n\n// Single init() traces all providers!\nambertrace.init({ apiKey: process.env.AMBERTRACE_API_KEY });\n\nconst openai = new OpenAI();\nconst anthropic = new Anthropic();\nconst genai = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!);\n\n// All calls are automatically traced\nconst gptResponse = await openai.chat.completions.create({\n  model: 'gpt-4',\n  messages: [{ role: 'user', content: 'Hello' }],\n});\n\nconst claudeResponse = await anthropic.messages.create({\n  model: 'claude-opus-4-5-20251101',\n  max_tokens: 100,\n  messages: [{ role: 'user', content: 'Hello' }],\n});\n\nconst geminiModel = genai.getGenerativeModel({ model: 'gemini-pro' });\nconst geminiResponse = await geminiModel.generateContent('Hello');\n\nawait ambertrace.flush();\n```\n\n## Framework Integration\n\nThe SDK works seamlessly with popular Node.js frameworks:\n\n- **Express.js** - Initialize at app startup, traces all LLM calls in routes\n- **NestJS** - Initialize in `main.ts`, works with all modules\n- **Next.js** - Initialize in API routes or middleware\n- **Fastify** - Initialize in startup hook\n- **Koa** - Initialize before app.listen()\n\nNo framework-specific configuration needed - just call `init()` once!\n\n## Trace Data Format\n\nAll traces follow a unified format regardless of provider:\n\n```typescript\ninterface Trace {\n  trace_id: string; // Unique UUID\n  timestamp: string; // ISO 8601 UTC\n  provider: 'openai' | 'anthropic' | 'google'; // Provider identifier\n  method: string; // API method name\n  duration_ms: number; // Call duration\n  request: {\n    model: string;\n    messages: Array<{ role: string; content: string }>;\n    parameters: Record<string, unknown>;\n  };\n  response?: {\n    id: string;\n    model: string;\n    choices: Array<{\n      index: number;\n      message: { role: string; content: string };\n      finish_reason: string;\n    }>;\n    usage: {\n      prompt_tokens: number;\n      completion_tokens: number;\n      total_tokens: number;\n    };\n  };\n  error?: {\n    type: string;\n    message: string;\n    code?: string;\n  };\n  sdk_version: string;\n  environment?: string;\n}\n```\n\n## Error Handling\n\nThe SDK follows a **never-fail** philosophy:\n\n- Network errors are logged but never thrown\n- Trace collection errors never impact your application\n- If the backend is unavailable, traces are silently dropped\n- Your LLM calls always succeed/fail based on the provider, not the SDK\n\nEnable `debug: true` to see trace delivery logs:\n\n```typescript\nambertrace.init({\n  apiKey: 'your-api-key',\n  debug: true, // See trace collection and delivery logs\n});\n```\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build (ESM + CommonJS + types)\nnpm run build\n\n# Run tests\nnpm test\n\n# Lint\nnpm run lint\n\n# Format\nnpm run format\n```\n\n## TypeScript Support\n\nThe SDK is written in TypeScript and includes complete type definitions:\n\n```typescript\nimport ambertrace, { type Trace, type ConfigOptions } from '@ambertrace/node';\n\nconst options: ConfigOptions = {\n  apiKey: 'your-api-key',\n  environment: 'production',\n};\n\nambertrace.init(options);\n```\n\n## License\n\nMIT\n\n## Support\n\n- **Issues**: [GitHub Issues](https://github.com/KirPros/ambertrace/issues)\n- **Documentation**: [GitHub README](https://github.com/KirPros/ambertrace#readme)\n- **Email**: hello@ambertrace.dev\n","readmeFilename":"README.md","_rev":"1-bd149713efd67faeb6c30a8ff39fd18a"}