@observyze/sdk 0.1.0 → 0.1.2

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,6 +1,6 @@
-# @observyze/sdk
+# Observyze Node.js SDK
 
-Node.js SDK for Observyze AI Observability Platform.
+The official Node.js SDK for Observyze.
 
 ## Installation
 
@@ -8,191 +8,26 @@ Node.js SDK for Observyze AI Observability Platform.
 npm install @observyze/sdk
 ```
 
-## Quick Start
-
-### Auto-Instrumentation (Recommended)
-
-The easiest way to get started is with auto-instrumentation:
+## Basic Usage
 
 ```typescript
-import OpenAI from 'openai'
 import { ObservyzeClient } from '@observyze/sdk'
+import OpenAI from 'openai'
 
-// Initialize Observyze
 const nw = new ObservyzeClient({
-  apiKey: process.env.Observyze_API_KEY!,
-  organizationId: 'your-org-id',
-  projectId: 'your-project-id'
+  apiKey: process.env.OBSERVYZE_API_KEY,
+  projectId: 'my-project'
 })
 
-// Initialize your LLM client
-const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY!
-})
+const openai = nw.wrap(new OpenAI())
 
-// Wrap the client - that's it!
-nw.wrap(openai)
-
-// All calls are now automatically traced
+// 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
+## Documentation
 
-MIT
+Full documentation is available at [observyze.com/docs](https://observyze.com/docs).

package/dist/chunk-YRMQCX2P.mjs

@@ -0,0 +1,372 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined") return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/types.ts
+var SpanType, TraceStatus;
+var init_types = __esm({
+  "src/types.ts"() {
+    "use strict";
+    SpanType = /* @__PURE__ */ ((SpanType3) => {
+      SpanType3["LLM"] = "llm";
+      SpanType3["TOOL"] = "tool";
+      SpanType3["AGENT"] = "agent";
+      SpanType3["CHAIN"] = "chain";
+      SpanType3["RETRIEVAL"] = "retrieval";
+      return SpanType3;
+    })(SpanType || {});
+    TraceStatus = /* @__PURE__ */ ((TraceStatus2) => {
+      TraceStatus2["SUCCESS"] = "success";
+      TraceStatus2["ERROR"] = "error";
+      TraceStatus2["TIMEOUT"] = "timeout";
+      TraceStatus2["RUNNING"] = "running";
+      return TraceStatus2;
+    })(TraceStatus || {});
+  }
+});
+
+// src/opentelemetry/exporter.ts
+init_types();
+
+// src/trace.ts
+init_types();
+import { randomUUID } from "crypto";
+function generateId() {
+  return `${Date.now()}-${randomUUID().substring(0, 8)}`;
+}
+var Span = class {
+  data;
+  startTime;
+  constructor(name, type, parentSpanId) {
+    this.startTime = Date.now();
+    this.data = {
+      span_id: generateId(),
+      parent_span_id: parentSpanId,
+      name,
+      type,
+      start_time: new Date(this.startTime),
+      end_time: new Date(this.startTime),
+      // Will be updated on end()
+      duration_ms: 0,
+      input: null,
+      output: null,
+      metadata: {}
+    };
+  }
+  /**
+   * Set the input data for this span
+   */
+  setInput(input) {
+    this.data.input = input;
+    return this;
+  }
+  /**
+   * Set the output data for this span
+   */
+  setOutput(output) {
+    this.data.output = output;
+    return this;
+  }
+  /**
+   * Record an error that occurred during span execution
+   */
+  setError(error) {
+    this.data.error = {
+      message: error.message,
+      stack: error.stack,
+      code: error.code
+    };
+    return this;
+  }
+  /**
+   * Set metadata for this span
+   */
+  setMetadata(key, value) {
+    this.data.metadata[key] = value;
+    return this;
+  }
+  /**
+   * Set multiple metadata fields at once
+   */
+  setMetadataAll(metadata) {
+    this.data.metadata = { ...this.data.metadata, ...metadata };
+    return this;
+  }
+  /**
+   * Set token usage information
+   */
+  setTokens(tokens) {
+    this.data.tokens = tokens;
+    return this;
+  }
+  /**
+   * End the span and calculate duration
+   */
+  end() {
+    const endTime = Date.now();
+    this.data.end_time = new Date(endTime);
+    this.data.duration_ms = endTime - this.startTime;
+  }
+  /**
+   * Get the span ID
+   */
+  get id() {
+    return this.data.span_id;
+  }
+  /**
+   * Get the span data for serialization
+   */
+  toJSON() {
+    return { ...this.data };
+  }
+};
+var Trace = class {
+  data;
+  startTime;
+  spans = [];
+  ended = false;
+  constructor(name, organizationId, projectId) {
+    this.startTime = Date.now();
+    this.data = {
+      trace_id: generateId(),
+      organization_id: organizationId,
+      project_id: projectId,
+      name,
+      status: "running" /* RUNNING */,
+      start_time: new Date(this.startTime),
+      end_time: new Date(this.startTime),
+      // Will be updated on end()
+      duration_ms: 0,
+      metadata: {},
+      spans: [],
+      tags: []
+    };
+  }
+  /**
+   * Start a new span within this trace
+   */
+  startSpan(name, type, parentSpanId) {
+    if (this.ended) {
+      throw new Error("Cannot start span on an ended trace");
+    }
+    const span = new Span(name, type, parentSpanId);
+    this.spans.push(span);
+    return span;
+  }
+  /**
+   * Add metadata to the trace
+   */
+  setMetadata(key, value) {
+    this.data.metadata[key] = value;
+    return this;
+  }
+  /**
+   * Set multiple metadata fields at once
+   */
+  setMetadataAll(metadata) {
+    this.data.metadata = { ...this.data.metadata, ...metadata };
+    return this;
+  }
+  /**
+   * Add tags to the trace
+   */
+  addTag(tag) {
+    if (!this.data.tags.includes(tag)) {
+      this.data.tags.push(tag);
+    }
+    return this;
+  }
+  /**
+   * Add multiple tags at once
+   */
+  addTags(tags) {
+    tags.forEach((tag) => this.addTag(tag));
+    return this;
+  }
+  /**
+   * Set the user ID associated with this trace
+   */
+  setUserId(userId) {
+    this.data.user_id = userId;
+    return this;
+  }
+  /**
+   * Set the session ID associated with this trace
+   */
+  setSessionId(sessionId) {
+    this.data.session_id = sessionId;
+    return this;
+  }
+  /**
+   * End the trace with a final status
+   */
+  end(status = "success" /* SUCCESS */) {
+    if (this.ended) {
+      return;
+    }
+    const endTime = Date.now();
+    this.data.end_time = new Date(endTime);
+    this.data.duration_ms = endTime - this.startTime;
+    this.data.status = status;
+    this.data.spans = this.spans.map((span) => span.toJSON());
+    this.ended = true;
+  }
+  /**
+   * Get the trace ID
+   */
+  get id() {
+    return this.data.trace_id;
+  }
+  /**
+   * Check if the trace has ended
+   */
+  get isEnded() {
+    return this.ended;
+  }
+  /**
+   * Get the trace data for serialization
+   */
+  toJSON() {
+    return { ...this.data };
+  }
+};
+
+// src/opentelemetry/exporter.ts
+var ObservyzeSpanExporter = class {
+  client;
+  config;
+  constructor(client, config) {
+    this.client = client;
+    this.config = {
+      serviceName: config?.serviceName || "unknown-service",
+      projectId: config?.projectId || "",
+      defaultSpanType: config?.defaultSpanType || "llm",
+      headers: config?.headers || {}
+    };
+  }
+  /**
+   * Export spans — called by OTel SDK when spans are ready.
+   * Converts OTel spans to Observyze traces and buffers them.
+   */
+  async export(spans, resultCallback) {
+    if (!spans || spans.length === 0) {
+      resultCallback({ code: 0 });
+      return;
+    }
+    try {
+      const organizationId = this.client.config?.organizationId || "";
+      const projectId = this.config.projectId || this.client.config?.projectId || "";
+      for (const span of spans) {
+        const spanContext = span.spanContext();
+        const traceId = spanContext?.traceId || span.spanId();
+        const trace = new Trace(
+          span.name || "otel-span",
+          organizationId,
+          projectId
+        );
+        trace.setMetadata("source", "opentelemetry");
+        trace.setMetadata("otel.trace_id", traceId);
+        trace.setMetadata("otel.span_id", spanContext?.spanId || "");
+        trace.setMetadata("service.name", this.config.serviceName);
+        trace.setMetadataAll(span.attributes || {});
+        if (span.resource?.attributes) {
+          trace.setMetadataAll(span.resource.attributes);
+        }
+        const input = span.attributes?.["gen_ai.prompt.0.content"] || span.attributes?.["gen_ai.completion.0.content"] || span.attributes?.["llm.input"] || void 0;
+        const output = span.attributes?.["gen_ai.completion.0.content"] || span.attributes?.["llm.output"] || void 0;
+        const model = span.attributes?.["gen_ai.request.model"] || span.attributes?.["llm.model"] || void 0;
+        const provider = span.attributes?.["gen_ai.request.provider"] || span.attributes?.["llm.provider"] || void 0;
+        const inputTokens = typeof span.attributes?.["gen_ai.usage.input_tokens"] === "number" ? span.attributes["gen_ai.usage.input_tokens"] : void 0;
+        const outputTokens = typeof span.attributes?.["gen_ai.usage.output_tokens"] === "number" ? span.attributes["gen_ai.usage.output_tokens"] : void 0;
+        trace.setMetadata("provider", provider || "unknown");
+        trace.setMetadata("model", model || "unknown");
+        const nsDuration = span.duration;
+        const durationMs = nsDuration ? Math.round(nsDuration / 1e6) : 0;
+        trace.setMetadata("latency_ms", durationMs);
+        trace.setMetadata("otel.duration_ns", nsDuration);
+        const oSpan = trace.startSpan(span.name || "otel-operation", this.config.defaultSpanType);
+        if (input) oSpan.setInput(input);
+        if (output) oSpan.setOutput(output);
+        if (inputTokens || outputTokens) {
+          oSpan.setTokens({
+            input: inputTokens || 0,
+            output: outputTokens || 0,
+            total: (inputTokens || 0) + (outputTokens || 0)
+          });
+        }
+        if (model) oSpan.setMetadata("model", model);
+        if (provider) oSpan.setMetadata("provider", provider);
+        if (span.attributes) oSpan.setMetadataAll(span.attributes);
+        const status = span.status;
+        const statusCode = status?.code;
+        if (statusCode === 2) {
+          oSpan.setError(new Error(status?.message || "OTel span error"));
+          trace.end("error" /* ERROR */);
+        } else {
+          trace.end("success" /* SUCCESS */);
+        }
+      }
+      resultCallback({ code: 0 });
+    } catch (error) {
+      resultCallback({
+        code: 1,
+        error: error instanceof Error ? error : new Error(String(error))
+      });
+    }
+  }
+  /**
+   * Called when the exporter is shut down.
+   * Flushes any remaining buffered traces via the SDK client.
+   */
+  async shutdown() {
+    try {
+      await this.client.flush();
+    } catch {
+    }
+  }
+  /**
+   * Called by the OTel SDK to force-export buffered spans.
+   */
+  async forceFlush() {
+    try {
+      await this.client.flush();
+    } catch {
+    }
+  }
+};
+
+export {
+  __require,
+  __esm,
+  __export,
+  __toCommonJS,
+  SpanType,
+  TraceStatus,
+  init_types,
+  Span,
+  Trace,
+  ObservyzeSpanExporter
+};