@observyze/sdk 0.1.3 → 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Observyze
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,198 +1,145 @@
-# @observyze/sdk
-
-Node.js SDK for Observyze AI Observability Platform.
-
-## Installation
-
-```bash
-npm install @observyze/sdk
-```
-
-## Quick Start
-
-### Auto-Instrumentation (Recommended)
-
-The easiest way to get started is with auto-instrumentation:
-
-```typescript
-import OpenAI from 'openai'
-import { ObservyzeClient } from '@observyze/sdk'
-
-// Initialize Observyze
-const nw = new ObservyzeClient({
-  apiKey: process.env.Observyze_API_KEY!,
-  organizationId: 'your-org-id',
-  projectId: 'your-project-id'
-})
-
-// Initialize your LLM client
-const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY!
-})
-
-// Wrap the client - that's it!
-nw.wrap(openai)
-
-// All calls are now automatically traced
-const response = await openai.chat.completions.create({
-  model: 'gpt-4',
-  messages: [{ role: 'user', content: 'Hello!' }]
-})
-```
-
-**Supported Providers:**
-- OpenAI (`chat.completions.create`)
-- Anthropic (`messages.create`)
-- Streaming responses fully supported
-
-See [Auto-Instrumentation Guide](./src/instrumentation/README.md) for more details.
-
-### Manual Instrumentation
-
-For more control, you can manually create traces and spans:
-
-```typescript
-import { ObservyzeClient, SpanType, TraceStatus } from '@observyze/sdk'
-
-// Initialize the client
-const nw = new ObservyzeClient({
-  apiKey: 'your-api-key',
-  endpoint: 'https://api.observyze.com',
-  projectId: 'your-project-id'
-})
-
-// Create a trace
-const trace = nw.startTrace('my-ai-workflow')
-
-// Add a span for an LLM call
-const span = trace.startSpan('openai-completion', SpanType.LLM)
-span.setInput({ prompt: 'Hello, world!' })
-span.setMetadata('model', 'gpt-4')
-span.setMetadata('temperature', 0.7)
-
-// ... perform your LLM call ...
-
-span.setOutput({ completion: 'Hello! How can I help you?' })
-span.setTokens({ input: 10, output: 15, total: 25 })
-span.end()
-
-// End the trace
-trace.end(TraceStatus.SUCCESS)
-
-// Flush traces (or wait for auto-flush)
-await nw.flush()
-
-// Shutdown when done
-await nw.shutdown()
-```
-
-## Configuration
-
-```typescript
-interface ClientConfig {
-  apiKey: string              // Required: Your Observyze API key
-  endpoint?: string           // Optional: Ingestion endpoint (default: http://localhost:3001)
-  batchSize?: number          // Optional: Max traces per batch (default: 100)
-  flushInterval?: number      // Optional: Auto-flush interval in ms (default: 5000)
-  organizationId?: string     // Optional: Organization ID
-  projectId?: string          // Optional: Project ID
-  debug?: boolean             // Optional: Enable debug logging (default: false)
-  dryRun?: boolean            // Optional: Don't send traces (default: false)
-}
-```
-
-## API Reference
-
-### ObservyzeClient
-
-#### `startTrace(name: string, metadata?: Record<string, any>): Trace`
-
-Start a new trace for an AI workflow.
-
-#### `flush(): Promise<void>`
-
-Manually flush buffered traces to the Ingestion Service.
-
-#### `shutdown(): Promise<void>`
-
-Shutdown the SDK and flush remaining traces.
-
-#### `wrap<T>(client: T): T`
-
-Wrap an LLM client (OpenAI, Anthropic) to enable auto-instrumentation. Returns the wrapped client.
-
-```typescript
-const openai = new OpenAI({ apiKey: 'key' })
-nw.wrap(openai)
-```
-
-### Trace
-
-#### `startSpan(name: string, type: SpanType, parentSpanId?: string): Span`
-
-Start a new span within the trace.
-
-#### `setMetadata(key: string, value: any): this`
-
-Add metadata to the trace.
-
-#### `addTag(tag: string): this`
-
-Add a tag to the trace.
-
-#### `setUserId(userId: string): this`
-
-Set the user ID associated with this trace.
-
-#### `setSessionId(sessionId: string): this`
-
-Set the session ID associated with this trace.
-
-#### `end(status?: TraceStatus): void`
-
-End the trace with a final status.
-
-### Span
-
-#### `setInput(input: any): this`
-
-Set the input data for the span.
-
-#### `setOutput(output: any): this`
-
-Set the output data for the span.
-
-#### `setError(error: Error): this`
-
-Record an error that occurred during span execution.
-
-#### `setMetadata(key: string, value: any): this`
-
-Add metadata to the span.
-
-#### `setTokens(tokens: TokenUsage): this`
-
-Set token usage information.
-
-#### `end(): void`
-
-End the span and calculate duration.
-
-## Span Types
-
-- `SpanType.LLM` - LLM API calls (OpenAI, Anthropic, etc.)
-- `SpanType.TOOL` - Tool invocations
-- `SpanType.AGENT` - Agent executions
-- `SpanType.CHAIN` - Chain operations
-- `SpanType.RETRIEVAL` - Retrieval operations (RAG)
-
-## Trace Status
-
-- `TraceStatus.SUCCESS` - Workflow completed successfully
-- `TraceStatus.ERROR` - Workflow failed with an error
-- `TraceStatus.TIMEOUT` - Workflow timed out
-- `TraceStatus.RUNNING` - Workflow is still running
-
-## License
-
-MIT
+# Observyze Node.js SDK
+
+[![npm version](https://img.shields.io/npm/v/@observyze/sdk.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/@observyze/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6.svg?style=flat-square)](https://www.typescriptlang.org/)
+
+The official TypeScript/Node.js SDK for [Observyze](https://observyze.com), an enterprise AI observability, evaluation, and governance platform.
+
+## Features
+
+- 🚀 **1-Line Auto-Instrumentation:** Support for OpenAI, Anthropic, Google Gemini, Vercel AI SDK, LangChain, and LlamaIndex.
+- 🔒 **Client-Side PII Redaction:** Redacts emails, credit cards, SSNs, API keys, passwords, and custom sensitive keys before data leaves your server.
+- ⚡ **Zero-Latency Async Buffering:** Non-blocking background flush with exponential backoff retries.
+- 🛡️ **Execution Budgets:** Limit tokens, API call counts, and execution deadlines for agentic workflows.
+- 🌐 **OpenTelemetry Exporter:** Plug directly into standard OpenTelemetry pipelines with `ObservyzeSpanExporter`.
+- 🔎 **End-to-End Connection Testing:** Built-in `testConnection()` utility.
+
+---
+
+## Installation
+
+```bash
+npm install @observyze/sdk
+```
+
+---
+
+## Quickstart
+
+### 1. OpenAI
+
+```typescript
+import { ObservyzeClient } from '@observyze/sdk'
+import OpenAI from 'openai'
+
+const nw = new ObservyzeClient({
+  apiKey: process.env.OBSERVYZE_API_KEY!,
+  projectId: 'my-ai-app'
+})
+
+const openai = nw.wrap(new OpenAI())
+
+// All chat completions are now automatically traced!
+const response = await openai.chat.completions.create({
+  model: 'gpt-4o',
+  messages: [{ role: 'user', content: 'Explain quantum computing simply.' }]
+})
+```
+
+### 2. Anthropic
+
+```typescript
+import { ObservyzeClient } from '@observyze/sdk'
+import Anthropic from '@anthropic-ai/sdk'
+
+const nw = new ObservyzeClient({ apiKey: process.env.OBSERVYZE_API_KEY! })
+const anthropic = nw.wrap(new Anthropic())
+
+const response = await anthropic.messages.create({
+  model: 'claude-3-5-sonnet-20241022',
+  max_tokens: 1024,
+  messages: [{ role: 'user', content: 'Hello, Claude!' }]
+})
+```
+
+### 3. Google Gemini
+
+```typescript
+import { ObservyzeClient, wrapGemini } from '@observyze/sdk'
+import { GoogleGenerativeAI } from '@google/generative-ai'
+
+const nw = new ObservyzeClient({ apiKey: process.env.OBSERVYZE_API_KEY! })
+const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY!)
+const model = wrapGemini(genAI.getGenerativeModel({ model: 'gemini-1.5-pro' }), nw)
+
+const result = await model.generateContent('Why is the sky blue?')
+```
+
+### 4. Vercel AI SDK
+
+```typescript
+import { ObservyzeClient, wrapVercelAI } from '@observyze/sdk'
+import { generateText, streamText } from 'ai'
+import { openai } from '@ai-sdk/openai'
+
+const nw = new ObservyzeClient({ apiKey: process.env.OBSERVYZE_API_KEY! })
+const ai = wrapVercelAI({ generateText, streamText }, nw)
+
+const { text } = await ai.generateText({
+  model: openai('gpt-4o'),
+  prompt: 'Write a haiku about AI observability.',
+})
+```
+
+---
+
+## Active Agent Execution Budgets
+
+Cap calls, tokens, and wall-clock duration for recursive or multi-step agent loops:
+
+```typescript
+const budget = nw.createExecutionBudget({
+  maxCalls: 15,
+  maxTokens: 40_000,
+  timeoutMs: 60_000,
+})
+
+const result = await budget.run(async (signal) => {
+  return openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'user', content: 'Run agent step' }]
+  }, { signal })
+})
+```
+
+---
+
+## Configuration
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | **Required** | Your Observyze API key |
+| `endpoint` | `string` | `https://api.observyze.com` | API endpoint |
+| `batchSize` | `number` | `100` | Max traces buffered before auto-flush |
+| `flushInterval` | `number` | `5000` | Flush interval in ms |
+| `enablePiiRedaction` | `boolean` | `true` | Client-side PII masking |
+| `captureContent` | `boolean` | `true` | Set to `false` for metadata-only mode |
+| `requestTimeoutMs` | `number` | `10000` | Per-request HTTP timeout in ms |
+| `dryRun` | `boolean` | `false` | Disable network delivery (for testing) |
+| `debug` | `boolean` | `false` | Enable verbose debug logging |
+
+---
+
+## Verify Integration
+
+```typescript
+const result = await nw.testConnection()
+console.log(result.ok, result.message)
+```
+
+---
+
+## License
+
+MIT © [Observyze](https://observyze.com)

package/dist/{chunk-FQBYUOJB.mjs → chunk-53PSEBAD.mjs}

@@ -1,20 +1,59 @@
 // src/types.ts
-import { SpanType, TraceStatus } from "@observyze/types";
+var SpanType = /* @__PURE__ */ ((SpanType3) => {
+  SpanType3["LLM"] = "llm";
+  SpanType3["TOOL"] = "tool";
+  SpanType3["AGENT"] = "agent";
+  SpanType3["CHAIN"] = "chain";
+  SpanType3["RETRIEVAL"] = "retrieval";
+  SpanType3["EMBEDDING"] = "embedding";
+  SpanType3["CUSTOM"] = "custom";
+  return SpanType3;
+})(SpanType || {});
+var TraceStatus = /* @__PURE__ */ ((TraceStatus2) => {
+  TraceStatus2["SUCCESS"] = "success";
+  TraceStatus2["ERROR"] = "error";
+  TraceStatus2["TIMEOUT"] = "timeout";
+  TraceStatus2["RUNNING"] = "running";
+  return TraceStatus2;
+})(TraceStatus || {});
 
 // src/trace.ts
 import { randomUUID } from "crypto";
 function generateId() {
   return `${Date.now()}-${randomUUID().substring(0, 8)}`;
 }
+var SAFE_OPERATIONAL_METADATA = /* @__PURE__ */ new Set([
+  "provider",
+  "model",
+  "temperature",
+  "max_tokens",
+  "max_completion_tokens",
+  "max_output_tokens",
+  "latency_ms",
+  "streaming",
+  "stream_completed",
+  "output_truncated",
+  "token_usage_source",
+  "cost_source",
+  "known_pricing",
+  "source",
+  "lifecycle",
+  "invocation_type"
+]);
+function isSafeOperationalValue(value) {
+  return value === null || ["string", "number", "boolean"].includes(typeof value);
+}
 var Span = class {
   data;
   startTime;
-  constructor(name, type, parentSpanId) {
+  captureContent;
+  constructor(name, type, parentSpanId, captureContent = true) {
     this.startTime = Date.now();
+    this.captureContent = captureContent;
     this.data = {
       span_id: generateId(),
       parent_span_id: parentSpanId,
-      name,
+      name: captureContent ? name : "[CONTENT_CAPTURE_DISABLED]",
       type,
       start_time: new Date(this.startTime),
       end_time: new Date(this.startTime),
@@ -29,14 +68,14 @@ var Span = class {
    * Set the input data for this span
    */
   setInput(input) {
-    this.data.input = input;
+    if (this.captureContent) this.data.input = input;
     return this;
   }
   /**
    * Set the output data for this span
    */
   setOutput(output) {
-    this.data.output = output;
+    if (this.captureContent) this.data.output = output;
     return this;
   }
   /**
@@ -44,9 +83,9 @@ var Span = class {
    */
   setError(error) {
     this.data.error = {
-      message: error.message,
-      stack: error.stack,
-      code: error.code
+      message: this.captureContent ? error.message : "Error details omitted because content capture is disabled",
+      stack: this.captureContent ? error.stack : void 0,
+      code: this.captureContent ? error.code : void 0
     };
     return this;
   }
@@ -54,14 +93,16 @@ var Span = class {
    * Set metadata for this span
    */
   setMetadata(key, value) {
-    this.data.metadata[key] = value;
+    if (this.captureContent || SAFE_OPERATIONAL_METADATA.has(key) && isSafeOperationalValue(value)) {
+      this.data.metadata[key] = value;
+    }
     return this;
   }
   /**
    * Set multiple metadata fields at once
    */
   setMetadataAll(metadata) {
-    this.data.metadata = { ...this.data.metadata, ...metadata };
+    for (const [key, value] of Object.entries(metadata)) this.setMetadata(key, value);
     return this;
   }
   /**
@@ -97,14 +138,16 @@ var Trace = class {
   startTime;
   spans = [];
   ended = false;
-  constructor(name, organizationId, projectId) {
+  captureContent;
+  constructor(name, organizationId, projectId, captureContent = true) {
     this.startTime = Date.now();
+    this.captureContent = captureContent;
     this.data = {
       trace_id: generateId(),
       organization_id: organizationId,
       project_id: projectId,
-      name,
-      status: TraceStatus.RUNNING,
+      name: captureContent ? name : "[CONTENT_CAPTURE_DISABLED]",
+      status: "running" /* RUNNING */,
       start_time: new Date(this.startTime),
       end_time: new Date(this.startTime),
       // Will be updated on end()
@@ -121,7 +164,7 @@ var Trace = class {
     if (this.ended) {
       throw new Error("Cannot start span on an ended trace");
     }
-    const span = new Span(name, type, parentSpanId);
+    const span = new Span(name, type, parentSpanId, this.captureContent);
     this.spans.push(span);
     return span;
   }
@@ -129,20 +172,23 @@ var Trace = class {
    * Add metadata to the trace
    */
   setMetadata(key, value) {
-    this.data.metadata[key] = value;
+    if (this.captureContent || SAFE_OPERATIONAL_METADATA.has(key) && isSafeOperationalValue(value)) {
+      this.data.metadata[key] = value;
+    }
     return this;
   }
   /**
    * Set multiple metadata fields at once
    */
   setMetadataAll(metadata) {
-    this.data.metadata = { ...this.data.metadata, ...metadata };
+    for (const [key, value] of Object.entries(metadata)) this.setMetadata(key, value);
     return this;
   }
   /**
    * Add tags to the trace
    */
   addTag(tag) {
+    if (!this.captureContent) return this;
     if (!this.data.tags.includes(tag)) {
       this.data.tags.push(tag);
     }
@@ -159,20 +205,20 @@ var Trace = class {
    * Set the user ID associated with this trace
    */
   setUserId(userId) {
-    this.data.user_id = userId;
+    if (this.captureContent) this.data.user_id = userId;
     return this;
   }
   /**
    * Set the session ID associated with this trace
    */
   setSessionId(sessionId) {
-    this.data.session_id = sessionId;
+    if (this.captureContent) this.data.session_id = sessionId;
     return this;
   }
   /**
    * End the trace with a final status
    */
-  end(status = TraceStatus.SUCCESS) {
+  end(status = "success" /* SUCCESS */) {
     if (this.ended) {
       return;
     }
@@ -273,9 +319,9 @@ var ObservyzeSpanExporter = class {
         const statusCode = status?.code;
         if (statusCode === 2) {
           oSpan.setError(new Error(status?.message || "OTel span error"));
-          trace.end(TraceStatus.ERROR);
+          trace.end("error" /* ERROR */);
         } else {
-          trace.end(TraceStatus.SUCCESS);
+          trace.end("success" /* SUCCESS */);
         }
       }
       resultCallback({ code: 0 });