observa-sdk 0.0.1

package/README.md

@@ -0,0 +1,251 @@
+# Observa SDK
+
+Enterprise-grade observability SDK for AI applications. Track and monitor LLM interactions with zero friction.
+
+## Installation
+
+```bash
+npm install observa-sdk
+```
+
+## Getting Started
+
+### 1. Sign Up
+
+Get your API key by signing up at [https://app.observa.ai/signup](https://app.observa.ai/signup) (or your Observa API endpoint).
+
+The signup process automatically:
+- Creates your tenant account
+- Sets up a default "Production" project
+- Provisions your Tinybird token
+- Generates your JWT API key
+
+You'll receive your API key immediately after signup.
+
+### 2. Install SDK
+
+```bash
+npm install observa-sdk
+```
+
+### 3. Initialize SDK
+
+```typescript
+import { init } from "observa-sdk";
+
+const observa = init({
+  apiKey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Your API key from signup
+});
+```
+
+## Quick Start
+
+### JWT-based API Key (Recommended)
+
+After signing up, you'll receive a JWT-formatted API key that automatically encodes your tenant and project context:
+
+```typescript
+import { init } from "observa-sdk";
+
+// Initialize with JWT API key from signup (automatically extracts tenant/project context)
+const observa = init({
+  apiKey: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // Your API key from signup
+});
+
+// Track AI interactions with simple wrapping
+const response = await observa.track(
+  { query: "What is the weather?" },
+  () => fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: { /* ... */ },
+    body: JSON.stringify({ /* ... */ }),
+  })
+);
+```
+
+### Legacy API Key Format
+
+```typescript
+// For backward compatibility, you can still provide tenantId/projectId explicitly
+const observa = init({
+  apiKey: "your-api-key",
+  tenantId: "acme_corp",
+  projectId: "prod_app",
+  environment: "prod", // optional, defaults to "dev"
+});
+```
+
+## Multi-Tenant Architecture
+
+Observa SDK uses a **multi-tenant shared runtime architecture** for optimal cost, scalability, and operational simplicity.
+
+### Architecture Pattern
+
+- **Shared Infrastructure**: Single Tinybird/ClickHouse cluster shared across all tenants
+- **Data Isolation**: Multi-layer isolation via partitioning, token scoping, and row-level security
+- **Performance**: Partitioned by tenant_id for efficient queries
+- **Security**: JWT-based authentication with automatic tenant context extraction
+
+### Data Storage
+
+All tenant data is stored in a single shared table with:
+
+- **Partitioning**: `PARTITION BY (tenant_id, toYYYYMM(date))`
+- **Ordering**: `ORDER BY (tenant_id, project_id, timestamp, trace_id)`
+- **Isolation**: Physical separation at partition level + logical separation via token scoping
+
+### Security Model
+
+1. **JWT Authentication**: API keys are JWTs encoding tenant/project context
+2. **Token Scoping**: Each tenant gets a Tinybird token scoped to their `tenant_id`
+3. **Automatic Filtering**: All queries automatically filtered by tenant context
+4. **Row-Level Security**: Token-based access control prevents cross-tenant access
+
+## JWT API Key Format
+
+The SDK supports JWT-formatted API keys that encode tenant context:
+
+```json
+{
+  "tenantId": "acme_corp",
+  "projectId": "prod_app",
+  "environment": "prod",
+  "iat": 1234567890,
+  "exp": 1234654290
+}
+```
+
+**JWT Structure**:
+- `tenantId` (required): Unique identifier for the tenant/organization
+- `projectId` (required): Project identifier within the tenant
+- `environment` (optional): `"dev"` or `"prod"` (defaults to `"dev"`)
+- `iat` (optional): Issued at timestamp
+- `exp` (optional): Expiration timestamp
+
+When using a JWT API key, the SDK automatically extracts `tenantId` and `projectId` - you don't need to provide them in the config.
+
+## Configuration
+
+```typescript
+interface ObservaInitConfig {
+  // API key (JWT or legacy format)
+  apiKey: string;
+
+  // Tenant context (optional if API key is JWT, required for legacy keys)
+  tenantId?: string;
+  projectId?: string;
+  environment?: "dev" | "prod";
+
+  // SDK behavior
+  mode?: "development" | "production";
+  sampleRate?: number; // 0..1, default: 1.0
+  maxResponseChars?: number; // default: 50000
+}
+```
+
+### Options
+
+- **apiKey**: Your Observa API key (JWT format recommended)
+- **tenantId** / **projectId**: Required only for legacy API keys
+- **environment**: `"dev"` or `"prod"` (defaults to `"dev"`)
+- **mode**: SDK mode - `"development"` logs traces to console, `"production"` sends to Observa
+- **sampleRate**: Fraction of traces to record (0.0 to 1.0)
+- **maxResponseChars**: Maximum response size to capture (prevents huge payloads)
+
+## API Reference
+
+### `init(config: ObservaInitConfig)`
+
+Initialize the Observa SDK instance.
+
+### `observa.track(event, action)`
+
+Track an AI interaction.
+
+**Parameters**:
+- `event.query` (required): The user query/prompt
+- `event.context` (optional): Additional context
+- `event.model` (optional): Model identifier
+- `event.metadata` (optional): Custom metadata
+- `action`: Function that returns a `Promise<Response>` (typically a fetch call)
+
+**Returns**: `Promise<Response>` (the original response, unmodified)
+
+**Example**:
+```typescript
+const response = await observa.track(
+  {
+    query: "What is machine learning?",
+    model: "gpt-4",
+    metadata: { userId: "123" },
+  },
+  () => fetch("https://api.openai.com/v1/chat/completions", {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${openaiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      model: "gpt-4",
+      messages: [{ role: "user", content: "What is machine learning?" }],
+    }),
+  })
+);
+```
+
+## Data Captured
+
+The SDK automatically captures:
+
+- **Request Data**: Query, context, model, metadata
+- **Response Data**: Full response text, response length
+- **Token Usage**: Prompt tokens, completion tokens, total tokens
+- **Performance Metrics**: Latency, time-to-first-token, streaming duration
+- **Response Metadata**: Status codes, finish reasons, response IDs
+- **Trace Information**: Trace ID, span ID, timestamps
+
+## Development Mode
+
+In development mode (`mode: "development"`), the SDK:
+
+- Logs beautifully formatted traces to the console
+- Still sends data to Observa (for testing)
+- Shows tenant context, performance metrics, and token usage
+
+## Production Mode
+
+In production mode (`mode: "production"` or `NODE_ENV=production`):
+
+- Data is sent to Observa backend
+- No console logs (except errors)
+- Optimized for performance
+
+## Multi-Tenant Isolation Guarantees
+
+1. **Storage Layer**: Data partitioned by `tenant_id` (physical separation)
+2. **Application Layer**: JWT encodes tenant context (logical separation)
+3. **API Layer**: Token-scoped access (row-level security)
+4. **Query Layer**: Automatic tenant filtering (no cross-tenant queries possible)
+
+## Browser & Node.js Support
+
+The SDK works in both browser and Node.js environments:
+
+- **Browser**: Uses `atob` for base64 decoding
+- **Node.js**: Uses `Buffer` for base64 decoding
+- **Universal**: No environment-specific dependencies
+
+## Onboarding Flow
+
+1. **Sign Up**: Visit the signup page and provide your email and company name
+2. **Get API Key**: Receive your JWT API key immediately
+3. **Install SDK**: `npm install observa-sdk`
+4. **Initialize**: Use your API key to initialize the SDK
+5. **Start Tracking**: Begin tracking your AI interactions
+
+The entire onboarding process takes less than 5 minutes, and you can start tracking traces immediately after signup.
+
+## License
+
+MIT
+

package/dist/index.cjs

@@ -0,0 +1,464 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Observa: () => Observa,
+  init: () => init
+});
+module.exports = __toCommonJS(index_exports);
+function getNodeEnv() {
+  try {
+    const proc = globalThis.process;
+    return proc?.env?.NODE_ENV;
+  } catch {
+    return void 0;
+  }
+}
+function decodeJWT(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      return null;
+    }
+    const payload = parts[1];
+    if (!payload) {
+      return null;
+    }
+    const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+    let decoded;
+    try {
+      if (typeof atob !== "undefined") {
+        decoded = atob(padded);
+      } else {
+        const BufferClass = globalThis.Buffer;
+        if (BufferClass) {
+          decoded = BufferClass.from(padded, "base64").toString("utf-8");
+        } else {
+          return null;
+        }
+      }
+    } catch {
+      return null;
+    }
+    return JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+}
+function extractTenantContextFromAPIKey(apiKey) {
+  const payload = decodeJWT(apiKey);
+  if (!payload) {
+    return null;
+  }
+  const tenantId = payload.tenantId;
+  const projectId = payload.projectId;
+  if (!tenantId || !projectId) {
+    return null;
+  }
+  const result = {
+    tenantId,
+    projectId
+  };
+  if (payload.environment !== void 0) {
+    result.environment = payload.environment;
+  }
+  return result;
+}
+function parseSSEChunk(chunk) {
+  const lines = chunk.split("\n");
+  for (const line of lines) {
+    if (!line.startsWith("data: ")) continue;
+    const payload = line.slice(6).trim();
+    if (payload === "[DONE]") return { done: true };
+    try {
+      return JSON.parse(payload);
+    } catch {
+    }
+  }
+  return {};
+}
+function extractMetadataFromChunks(chunks) {
+  let tokensPrompt;
+  let tokensCompletion;
+  let tokensTotal;
+  let model;
+  let finishReason;
+  let responseId;
+  let systemFingerprint;
+  for (const chunk of chunks) {
+    const parsed = parseSSEChunk(chunk);
+    if (parsed?.usage) {
+      tokensPrompt = parsed.usage.prompt_tokens ?? tokensPrompt;
+      tokensCompletion = parsed.usage.completion_tokens ?? tokensCompletion;
+      tokensTotal = parsed.usage.total_tokens ?? tokensTotal;
+    }
+    if (parsed?.model && !model) model = parsed.model;
+    if (parsed?.id && !responseId) responseId = parsed.id;
+    if (parsed?.system_fingerprint && !systemFingerprint)
+      systemFingerprint = parsed.system_fingerprint;
+    const fr = parsed?.choices?.[0]?.finish_reason;
+    if (fr && !finishReason) finishReason = fr;
+  }
+  return {
+    tokensPrompt: tokensPrompt ?? null,
+    tokensCompletion: tokensCompletion ?? null,
+    tokensTotal: tokensTotal ?? null,
+    model: model ?? null,
+    finishReason: finishReason ?? null,
+    responseId: responseId ?? null,
+    systemFingerprint: systemFingerprint ?? null
+  };
+}
+function formatBeautifulLog(trace) {
+  const colors = {
+    reset: "\x1B[0m",
+    bright: "\x1B[1m",
+    dim: "\x1B[2m",
+    blue: "\x1B[34m",
+    cyan: "\x1B[36m",
+    green: "\x1B[32m",
+    yellow: "\x1B[33m",
+    magenta: "\x1B[35m",
+    gray: "\x1B[90m"
+  };
+  const formatValue = (label, value, color = colors.cyan) => `${colors.dim}${label}:${colors.reset} ${color}${value}${colors.reset}`;
+  console.log("\n" + "\u2550".repeat(90));
+  console.log(
+    `${colors.bright}${colors.blue}\u{1F50D} OBSERVA TRACE${colors.reset} ${colors.gray}${trace.traceId}${colors.reset}`
+  );
+  console.log("\u2500".repeat(90));
+  console.log(`${colors.bright}\u{1F3F7} Tenant${colors.reset}`);
+  console.log(`  ${formatValue("tenantId", trace.tenantId, colors.gray)}`);
+  console.log(`  ${formatValue("projectId", trace.projectId, colors.gray)}`);
+  console.log(`  ${formatValue("env", trace.environment, colors.gray)}`);
+  console.log(`
+${colors.bright}\u{1F4CB} Request${colors.reset}`);
+  console.log(
+    `  ${formatValue(
+      "Timestamp",
+      new Date(trace.timestamp).toLocaleString(),
+      colors.gray
+    )}`
+  );
+  if (trace.model)
+    console.log(`  ${formatValue("Model", trace.model, colors.yellow)}`);
+  const queryPreview = trace.query.length > 80 ? trace.query.slice(0, 80) + "..." : trace.query;
+  console.log(`  ${formatValue("Query", queryPreview, colors.green)}`);
+  if (trace.context) {
+    const ctxPreview = trace.context.length > 120 ? trace.context.slice(0, 120) + "..." : trace.context;
+    console.log(`  ${formatValue("Context", ctxPreview, colors.cyan)}`);
+  }
+  console.log(`
+${colors.bright}\u26A1 Performance${colors.reset}`);
+  console.log(
+    `  ${formatValue("Latency", `${trace.latencyMs}ms`, colors.green)}`
+  );
+  if (trace.timeToFirstTokenMs != null) {
+    console.log(
+      `  ${formatValue("TTFB", `${trace.timeToFirstTokenMs}ms`, colors.cyan)}`
+    );
+  }
+  if (trace.streamingDurationMs != null) {
+    console.log(
+      `  ${formatValue(
+        "Streaming",
+        `${trace.streamingDurationMs}ms`,
+        colors.cyan
+      )}`
+    );
+  }
+  console.log(`
+${colors.bright}\u{1FA99} Tokens${colors.reset}`);
+  if (trace.tokensPrompt != null)
+    console.log(`  ${formatValue("Prompt", trace.tokensPrompt)}`);
+  if (trace.tokensCompletion != null)
+    console.log(`  ${formatValue("Completion", trace.tokensCompletion)}`);
+  if (trace.tokensTotal != null)
+    console.log(
+      `  ${formatValue(
+        "Total",
+        trace.tokensTotal,
+        colors.bright + colors.yellow
+      )}`
+    );
+  console.log(`
+${colors.bright}\u{1F4E4} Response${colors.reset}`);
+  console.log(
+    `  ${formatValue(
+      "Length",
+      `${trace.responseLength.toLocaleString()} chars`,
+      colors.cyan
+    )}`
+  );
+  if (trace.status != null) {
+    const statusColor = trace.status >= 200 && trace.status < 300 ? colors.green : colors.yellow;
+    console.log(
+      `  ${formatValue(
+        "Status",
+        `${trace.status} ${trace.statusText ?? ""}`,
+        statusColor
+      )}`
+    );
+  }
+  if (trace.finishReason)
+    console.log(
+      `  ${formatValue("Finish", trace.finishReason, colors.magenta)}`
+    );
+  const respPreview = trace.response.length > 300 ? trace.response.slice(0, 300) + "..." : trace.response;
+  console.log(`
+${colors.bright}\u{1F4AC} Response Preview${colors.reset}`);
+  console.log(`${colors.dim}${respPreview}${colors.reset}`);
+  if (trace.metadata && Object.keys(trace.metadata).length) {
+    console.log(`
+${colors.bright}\u{1F4CE} Metadata${colors.reset}`);
+    for (const [k, v] of Object.entries(trace.metadata)) {
+      const valueStr = typeof v === "object" ? JSON.stringify(v) : String(v);
+      console.log(`  ${formatValue(k, valueStr, colors.gray)}`);
+    }
+  }
+  console.log("\u2550".repeat(90) + "\n");
+}
+var Observa = class {
+  apiKey;
+  tenantId;
+  projectId;
+  environment;
+  apiUrl;
+  isProduction;
+  sampleRate;
+  maxResponseChars;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    let apiUrlEnv;
+    try {
+      const proc = globalThis.process;
+      apiUrlEnv = proc?.env?.OBSERVA_API_URL;
+    } catch {
+    }
+    this.apiUrl = config.apiUrl || apiUrlEnv || "https://api.observa.ai";
+    const jwtContext = extractTenantContextFromAPIKey(config.apiKey);
+    if (jwtContext) {
+      this.tenantId = jwtContext.tenantId;
+      this.projectId = jwtContext.projectId;
+      this.environment = jwtContext.environment ?? config.environment ?? "dev";
+    } else {
+      if (!config.tenantId || !config.projectId) {
+        throw new Error(
+          "Observa SDK: tenantId and projectId are required when using legacy API key format. Either provide a JWT-formatted API key (which encodes tenant/project context) or explicitly provide tenantId and projectId in the config."
+        );
+      }
+      this.tenantId = config.tenantId;
+      this.projectId = config.projectId;
+      this.environment = config.environment ?? "dev";
+    }
+    if (!this.tenantId || !this.projectId) {
+      throw new Error(
+        "Observa SDK: tenantId and projectId must be set. This should never happen - please report this error."
+      );
+    }
+    const nodeEnv = getNodeEnv();
+    this.isProduction = config.mode === "production" || nodeEnv === "production";
+    this.sampleRate = typeof config.sampleRate === "number" ? config.sampleRate : 1;
+    this.maxResponseChars = config.maxResponseChars ?? 5e4;
+    console.log(
+      `\u{1F4A7} Observa SDK Initialized (${this.isProduction ? "production" : "development"})`
+    );
+    if (!this.isProduction) {
+      console.log(`\u{1F517} [Observa] API URL: ${this.apiUrl}`);
+      console.log(`\u{1F517} [Observa] Tenant: ${this.tenantId}`);
+      console.log(`\u{1F517} [Observa] Project: ${this.projectId}`);
+      console.log(
+        `\u{1F517} [Observa] Auth: ${jwtContext ? "JWT (auto-extracted)" : "Legacy (config)"}`
+      );
+    }
+  }
+  async track(event, action) {
+    if (this.sampleRate < 1 && Math.random() > this.sampleRate) {
+      return action();
+    }
+    const startTime = Date.now();
+    const traceId = crypto.randomUUID();
+    const spanId = traceId;
+    const originalResponse = await action();
+    if (!originalResponse.body) return originalResponse;
+    const responseHeaders = {};
+    originalResponse.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+    const [stream1, stream2] = originalResponse.body.tee();
+    this.captureStream({
+      stream: stream2,
+      event,
+      traceId,
+      spanId,
+      parentSpanId: null,
+      startTime,
+      status: originalResponse.status,
+      statusText: originalResponse.statusText,
+      headers: responseHeaders
+    });
+    return new Response(stream1, {
+      headers: originalResponse.headers,
+      status: originalResponse.status,
+      statusText: originalResponse.statusText
+    });
+  }
+  async captureStream(args) {
+    const {
+      stream,
+      event,
+      traceId,
+      spanId,
+      parentSpanId,
+      startTime,
+      status,
+      statusText,
+      headers
+    } = args;
+    try {
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+      let fullResponse = "";
+      let firstTokenTime;
+      const chunks = [];
+      let buffer = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (!firstTokenTime && value && value.length > 0) {
+          firstTokenTime = Date.now();
+        }
+        const chunk = decoder.decode(value, { stream: true });
+        chunks.push(chunk);
+        buffer += chunk;
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const data = line.slice(6).trim();
+          if (!data || data === "[DONE]") continue;
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed?.choices?.[0]?.delta?.content) {
+              fullResponse += parsed.choices[0].delta.content;
+            } else if (parsed?.choices?.[0]?.text) {
+              fullResponse += parsed.choices[0].text;
+            } else if (typeof parsed?.content === "string") {
+              fullResponse += parsed.content;
+            }
+          } catch {
+            fullResponse += data;
+          }
+        }
+        if (fullResponse.length > this.maxResponseChars) {
+          fullResponse = fullResponse.slice(0, this.maxResponseChars) + "\u2026[TRUNCATED]";
+          break;
+        }
+      }
+      if (buffer.trim()) {
+        fullResponse += buffer;
+      }
+      const endTime = Date.now();
+      const latencyMs = endTime - startTime;
+      const timeToFirstTokenMs = firstTokenTime != null ? firstTokenTime - startTime : null;
+      const streamingDurationMs = firstTokenTime != null ? endTime - firstTokenTime : null;
+      const extracted = extractMetadataFromChunks(chunks);
+      if (!this.tenantId || !this.projectId) {
+        throw new Error(
+          "Observa SDK: tenantId and projectId must be set. This indicates a SDK configuration error."
+        );
+      }
+      const traceData = {
+        traceId,
+        spanId,
+        parentSpanId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        tenantId: this.tenantId,
+        projectId: this.projectId,
+        environment: this.environment,
+        query: event.query,
+        ...event.context !== void 0 && { context: event.context },
+        ...(extracted.model ?? event.model) !== void 0 && {
+          model: extracted.model ?? event.model
+        },
+        ...event.metadata !== void 0 && { metadata: event.metadata },
+        response: fullResponse,
+        responseLength: fullResponse.length,
+        tokensPrompt: extracted.tokensPrompt ?? null,
+        tokensCompletion: extracted.tokensCompletion ?? null,
+        tokensTotal: extracted.tokensTotal ?? null,
+        latencyMs,
+        timeToFirstTokenMs,
+        streamingDurationMs,
+        status: status ?? null,
+        statusText: statusText ?? null,
+        finishReason: extracted.finishReason ?? null,
+        responseId: extracted.responseId ?? null,
+        systemFingerprint: extracted.systemFingerprint ?? null,
+        ...headers !== void 0 && { headers }
+      };
+      await this.sendTrace(traceData);
+    } catch (err) {
+      console.error("[Observa] Error capturing stream:", err);
+    }
+  }
+  async sendTrace(trace) {
+    if (!this.isProduction) {
+      formatBeautifulLog(trace);
+    }
+    try {
+      const url = `${this.apiUrl}/api/v1/traces/ingest`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(trace)
+      });
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "Unknown error");
+        let errorJson;
+        try {
+          errorJson = JSON.parse(errorText);
+        } catch {
+          errorJson = { error: errorText };
+        }
+        console.error(
+          `[Observa] Backend API error: ${response.status} ${response.statusText}`,
+          errorJson.error || errorText
+        );
+      } else if (!this.isProduction) {
+        console.log(`\u2705 [Observa] Trace sent successfully`);
+        console.log(`   Trace ID: ${trace.traceId}`);
+      }
+    } catch (error) {
+      console.error("[Observa] Failed to send trace:", error);
+    }
+  }
+};
+var init = (config) => new Observa(config);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Observa,
+  init
+});

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+interface ObservaInitConfig {
+    apiKey: string;
+    tenantId?: string;
+    projectId?: string;
+    environment?: "dev" | "prod";
+    apiUrl?: string;
+    mode?: "development" | "production";
+    sampleRate?: number;
+    maxResponseChars?: number;
+}
+interface TrackEventInput {
+    query: string;
+    context?: string;
+    model?: string;
+    metadata?: Record<string, any>;
+}
+declare class Observa {
+    private apiKey;
+    private tenantId;
+    private projectId;
+    private environment;
+    private apiUrl;
+    private isProduction;
+    private sampleRate;
+    private maxResponseChars;
+    constructor(config: ObservaInitConfig);
+    track(event: TrackEventInput, action: () => Promise<Response>): Promise<Response>;
+    private captureStream;
+    private sendTrace;
+}
+declare const init: (config: ObservaInitConfig) => Observa;
+
+export { Observa, type ObservaInitConfig, type TrackEventInput, init };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+interface ObservaInitConfig {
+    apiKey: string;
+    tenantId?: string;
+    projectId?: string;
+    environment?: "dev" | "prod";
+    apiUrl?: string;
+    mode?: "development" | "production";
+    sampleRate?: number;
+    maxResponseChars?: number;
+}
+interface TrackEventInput {
+    query: string;
+    context?: string;
+    model?: string;
+    metadata?: Record<string, any>;
+}
+declare class Observa {
+    private apiKey;
+    private tenantId;
+    private projectId;
+    private environment;
+    private apiUrl;
+    private isProduction;
+    private sampleRate;
+    private maxResponseChars;
+    constructor(config: ObservaInitConfig);
+    track(event: TrackEventInput, action: () => Promise<Response>): Promise<Response>;
+    private captureStream;
+    private sendTrace;
+}
+declare const init: (config: ObservaInitConfig) => Observa;
+
+export { Observa, type ObservaInitConfig, type TrackEventInput, init };

package/dist/index.js

@@ -0,0 +1,438 @@
+// src/index.ts
+function getNodeEnv() {
+  try {
+    const proc = globalThis.process;
+    return proc?.env?.NODE_ENV;
+  } catch {
+    return void 0;
+  }
+}
+function decodeJWT(token) {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      return null;
+    }
+    const payload = parts[1];
+    if (!payload) {
+      return null;
+    }
+    const base64 = payload.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = base64 + "=".repeat((4 - base64.length % 4) % 4);
+    let decoded;
+    try {
+      if (typeof atob !== "undefined") {
+        decoded = atob(padded);
+      } else {
+        const BufferClass = globalThis.Buffer;
+        if (BufferClass) {
+          decoded = BufferClass.from(padded, "base64").toString("utf-8");
+        } else {
+          return null;
+        }
+      }
+    } catch {
+      return null;
+    }
+    return JSON.parse(decoded);
+  } catch {
+    return null;
+  }
+}
+function extractTenantContextFromAPIKey(apiKey) {
+  const payload = decodeJWT(apiKey);
+  if (!payload) {
+    return null;
+  }
+  const tenantId = payload.tenantId;
+  const projectId = payload.projectId;
+  if (!tenantId || !projectId) {
+    return null;
+  }
+  const result = {
+    tenantId,
+    projectId
+  };
+  if (payload.environment !== void 0) {
+    result.environment = payload.environment;
+  }
+  return result;
+}
+function parseSSEChunk(chunk) {
+  const lines = chunk.split("\n");
+  for (const line of lines) {
+    if (!line.startsWith("data: ")) continue;
+    const payload = line.slice(6).trim();
+    if (payload === "[DONE]") return { done: true };
+    try {
+      return JSON.parse(payload);
+    } catch {
+    }
+  }
+  return {};
+}
+function extractMetadataFromChunks(chunks) {
+  let tokensPrompt;
+  let tokensCompletion;
+  let tokensTotal;
+  let model;
+  let finishReason;
+  let responseId;
+  let systemFingerprint;
+  for (const chunk of chunks) {
+    const parsed = parseSSEChunk(chunk);
+    if (parsed?.usage) {
+      tokensPrompt = parsed.usage.prompt_tokens ?? tokensPrompt;
+      tokensCompletion = parsed.usage.completion_tokens ?? tokensCompletion;
+      tokensTotal = parsed.usage.total_tokens ?? tokensTotal;
+    }
+    if (parsed?.model && !model) model = parsed.model;
+    if (parsed?.id && !responseId) responseId = parsed.id;
+    if (parsed?.system_fingerprint && !systemFingerprint)
+      systemFingerprint = parsed.system_fingerprint;
+    const fr = parsed?.choices?.[0]?.finish_reason;
+    if (fr && !finishReason) finishReason = fr;
+  }
+  return {
+    tokensPrompt: tokensPrompt ?? null,
+    tokensCompletion: tokensCompletion ?? null,
+    tokensTotal: tokensTotal ?? null,
+    model: model ?? null,
+    finishReason: finishReason ?? null,
+    responseId: responseId ?? null,
+    systemFingerprint: systemFingerprint ?? null
+  };
+}
+function formatBeautifulLog(trace) {
+  const colors = {
+    reset: "\x1B[0m",
+    bright: "\x1B[1m",
+    dim: "\x1B[2m",
+    blue: "\x1B[34m",
+    cyan: "\x1B[36m",
+    green: "\x1B[32m",
+    yellow: "\x1B[33m",
+    magenta: "\x1B[35m",
+    gray: "\x1B[90m"
+  };
+  const formatValue = (label, value, color = colors.cyan) => `${colors.dim}${label}:${colors.reset} ${color}${value}${colors.reset}`;
+  console.log("\n" + "\u2550".repeat(90));
+  console.log(
+    `${colors.bright}${colors.blue}\u{1F50D} OBSERVA TRACE${colors.reset} ${colors.gray}${trace.traceId}${colors.reset}`
+  );
+  console.log("\u2500".repeat(90));
+  console.log(`${colors.bright}\u{1F3F7} Tenant${colors.reset}`);
+  console.log(`  ${formatValue("tenantId", trace.tenantId, colors.gray)}`);
+  console.log(`  ${formatValue("projectId", trace.projectId, colors.gray)}`);
+  console.log(`  ${formatValue("env", trace.environment, colors.gray)}`);
+  console.log(`
+${colors.bright}\u{1F4CB} Request${colors.reset}`);
+  console.log(
+    `  ${formatValue(
+      "Timestamp",
+      new Date(trace.timestamp).toLocaleString(),
+      colors.gray
+    )}`
+  );
+  if (trace.model)
+    console.log(`  ${formatValue("Model", trace.model, colors.yellow)}`);
+  const queryPreview = trace.query.length > 80 ? trace.query.slice(0, 80) + "..." : trace.query;
+  console.log(`  ${formatValue("Query", queryPreview, colors.green)}`);
+  if (trace.context) {
+    const ctxPreview = trace.context.length > 120 ? trace.context.slice(0, 120) + "..." : trace.context;
+    console.log(`  ${formatValue("Context", ctxPreview, colors.cyan)}`);
+  }
+  console.log(`
+${colors.bright}\u26A1 Performance${colors.reset}`);
+  console.log(
+    `  ${formatValue("Latency", `${trace.latencyMs}ms`, colors.green)}`
+  );
+  if (trace.timeToFirstTokenMs != null) {
+    console.log(
+      `  ${formatValue("TTFB", `${trace.timeToFirstTokenMs}ms`, colors.cyan)}`
+    );
+  }
+  if (trace.streamingDurationMs != null) {
+    console.log(
+      `  ${formatValue(
+        "Streaming",
+        `${trace.streamingDurationMs}ms`,
+        colors.cyan
+      )}`
+    );
+  }
+  console.log(`
+${colors.bright}\u{1FA99} Tokens${colors.reset}`);
+  if (trace.tokensPrompt != null)
+    console.log(`  ${formatValue("Prompt", trace.tokensPrompt)}`);
+  if (trace.tokensCompletion != null)
+    console.log(`  ${formatValue("Completion", trace.tokensCompletion)}`);
+  if (trace.tokensTotal != null)
+    console.log(
+      `  ${formatValue(
+        "Total",
+        trace.tokensTotal,
+        colors.bright + colors.yellow
+      )}`
+    );
+  console.log(`
+${colors.bright}\u{1F4E4} Response${colors.reset}`);
+  console.log(
+    `  ${formatValue(
+      "Length",
+      `${trace.responseLength.toLocaleString()} chars`,
+      colors.cyan
+    )}`
+  );
+  if (trace.status != null) {
+    const statusColor = trace.status >= 200 && trace.status < 300 ? colors.green : colors.yellow;
+    console.log(
+      `  ${formatValue(
+        "Status",
+        `${trace.status} ${trace.statusText ?? ""}`,
+        statusColor
+      )}`
+    );
+  }
+  if (trace.finishReason)
+    console.log(
+      `  ${formatValue("Finish", trace.finishReason, colors.magenta)}`
+    );
+  const respPreview = trace.response.length > 300 ? trace.response.slice(0, 300) + "..." : trace.response;
+  console.log(`
+${colors.bright}\u{1F4AC} Response Preview${colors.reset}`);
+  console.log(`${colors.dim}${respPreview}${colors.reset}`);
+  if (trace.metadata && Object.keys(trace.metadata).length) {
+    console.log(`
+${colors.bright}\u{1F4CE} Metadata${colors.reset}`);
+    for (const [k, v] of Object.entries(trace.metadata)) {
+      const valueStr = typeof v === "object" ? JSON.stringify(v) : String(v);
+      console.log(`  ${formatValue(k, valueStr, colors.gray)}`);
+    }
+  }
+  console.log("\u2550".repeat(90) + "\n");
+}
+var Observa = class {
+  apiKey;
+  tenantId;
+  projectId;
+  environment;
+  apiUrl;
+  isProduction;
+  sampleRate;
+  maxResponseChars;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    let apiUrlEnv;
+    try {
+      const proc = globalThis.process;
+      apiUrlEnv = proc?.env?.OBSERVA_API_URL;
+    } catch {
+    }
+    this.apiUrl = config.apiUrl || apiUrlEnv || "https://api.observa.ai";
+    const jwtContext = extractTenantContextFromAPIKey(config.apiKey);
+    if (jwtContext) {
+      this.tenantId = jwtContext.tenantId;
+      this.projectId = jwtContext.projectId;
+      this.environment = jwtContext.environment ?? config.environment ?? "dev";
+    } else {
+      if (!config.tenantId || !config.projectId) {
+        throw new Error(
+          "Observa SDK: tenantId and projectId are required when using legacy API key format. Either provide a JWT-formatted API key (which encodes tenant/project context) or explicitly provide tenantId and projectId in the config."
+        );
+      }
+      this.tenantId = config.tenantId;
+      this.projectId = config.projectId;
+      this.environment = config.environment ?? "dev";
+    }
+    if (!this.tenantId || !this.projectId) {
+      throw new Error(
+        "Observa SDK: tenantId and projectId must be set. This should never happen - please report this error."
+      );
+    }
+    const nodeEnv = getNodeEnv();
+    this.isProduction = config.mode === "production" || nodeEnv === "production";
+    this.sampleRate = typeof config.sampleRate === "number" ? config.sampleRate : 1;
+    this.maxResponseChars = config.maxResponseChars ?? 5e4;
+    console.log(
+      `\u{1F4A7} Observa SDK Initialized (${this.isProduction ? "production" : "development"})`
+    );
+    if (!this.isProduction) {
+      console.log(`\u{1F517} [Observa] API URL: ${this.apiUrl}`);
+      console.log(`\u{1F517} [Observa] Tenant: ${this.tenantId}`);
+      console.log(`\u{1F517} [Observa] Project: ${this.projectId}`);
+      console.log(
+        `\u{1F517} [Observa] Auth: ${jwtContext ? "JWT (auto-extracted)" : "Legacy (config)"}`
+      );
+    }
+  }
+  async track(event, action) {
+    if (this.sampleRate < 1 && Math.random() > this.sampleRate) {
+      return action();
+    }
+    const startTime = Date.now();
+    const traceId = crypto.randomUUID();
+    const spanId = traceId;
+    const originalResponse = await action();
+    if (!originalResponse.body) return originalResponse;
+    const responseHeaders = {};
+    originalResponse.headers.forEach((value, key) => {
+      responseHeaders[key] = value;
+    });
+    const [stream1, stream2] = originalResponse.body.tee();
+    this.captureStream({
+      stream: stream2,
+      event,
+      traceId,
+      spanId,
+      parentSpanId: null,
+      startTime,
+      status: originalResponse.status,
+      statusText: originalResponse.statusText,
+      headers: responseHeaders
+    });
+    return new Response(stream1, {
+      headers: originalResponse.headers,
+      status: originalResponse.status,
+      statusText: originalResponse.statusText
+    });
+  }
+  async captureStream(args) {
+    const {
+      stream,
+      event,
+      traceId,
+      spanId,
+      parentSpanId,
+      startTime,
+      status,
+      statusText,
+      headers
+    } = args;
+    try {
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+      let fullResponse = "";
+      let firstTokenTime;
+      const chunks = [];
+      let buffer = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        if (!firstTokenTime && value && value.length > 0) {
+          firstTokenTime = Date.now();
+        }
+        const chunk = decoder.decode(value, { stream: true });
+        chunks.push(chunk);
+        buffer += chunk;
+        const lines = buffer.split("\n");
+        buffer = lines.pop() || "";
+        for (const line of lines) {
+          if (!line.startsWith("data: ")) continue;
+          const data = line.slice(6).trim();
+          if (!data || data === "[DONE]") continue;
+          try {
+            const parsed = JSON.parse(data);
+            if (parsed?.choices?.[0]?.delta?.content) {
+              fullResponse += parsed.choices[0].delta.content;
+            } else if (parsed?.choices?.[0]?.text) {
+              fullResponse += parsed.choices[0].text;
+            } else if (typeof parsed?.content === "string") {
+              fullResponse += parsed.content;
+            }
+          } catch {
+            fullResponse += data;
+          }
+        }
+        if (fullResponse.length > this.maxResponseChars) {
+          fullResponse = fullResponse.slice(0, this.maxResponseChars) + "\u2026[TRUNCATED]";
+          break;
+        }
+      }
+      if (buffer.trim()) {
+        fullResponse += buffer;
+      }
+      const endTime = Date.now();
+      const latencyMs = endTime - startTime;
+      const timeToFirstTokenMs = firstTokenTime != null ? firstTokenTime - startTime : null;
+      const streamingDurationMs = firstTokenTime != null ? endTime - firstTokenTime : null;
+      const extracted = extractMetadataFromChunks(chunks);
+      if (!this.tenantId || !this.projectId) {
+        throw new Error(
+          "Observa SDK: tenantId and projectId must be set. This indicates a SDK configuration error."
+        );
+      }
+      const traceData = {
+        traceId,
+        spanId,
+        parentSpanId,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        tenantId: this.tenantId,
+        projectId: this.projectId,
+        environment: this.environment,
+        query: event.query,
+        ...event.context !== void 0 && { context: event.context },
+        ...(extracted.model ?? event.model) !== void 0 && {
+          model: extracted.model ?? event.model
+        },
+        ...event.metadata !== void 0 && { metadata: event.metadata },
+        response: fullResponse,
+        responseLength: fullResponse.length,
+        tokensPrompt: extracted.tokensPrompt ?? null,
+        tokensCompletion: extracted.tokensCompletion ?? null,
+        tokensTotal: extracted.tokensTotal ?? null,
+        latencyMs,
+        timeToFirstTokenMs,
+        streamingDurationMs,
+        status: status ?? null,
+        statusText: statusText ?? null,
+        finishReason: extracted.finishReason ?? null,
+        responseId: extracted.responseId ?? null,
+        systemFingerprint: extracted.systemFingerprint ?? null,
+        ...headers !== void 0 && { headers }
+      };
+      await this.sendTrace(traceData);
+    } catch (err) {
+      console.error("[Observa] Error capturing stream:", err);
+    }
+  }
+  async sendTrace(trace) {
+    if (!this.isProduction) {
+      formatBeautifulLog(trace);
+    }
+    try {
+      const url = `${this.apiUrl}/api/v1/traces/ingest`;
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(trace)
+      });
+      if (!response.ok) {
+        const errorText = await response.text().catch(() => "Unknown error");
+        let errorJson;
+        try {
+          errorJson = JSON.parse(errorText);
+        } catch {
+          errorJson = { error: errorText };
+        }
+        console.error(
+          `[Observa] Backend API error: ${response.status} ${response.statusText}`,
+          errorJson.error || errorText
+        );
+      } else if (!this.isProduction) {
+        console.log(`\u2705 [Observa] Trace sent successfully`);
+        console.log(`   Trace ID: ${trace.traceId}`);
+      }
+    } catch (error) {
+      console.error("[Observa] Failed to send trace:", error);
+    }
+  }
+};
+var init = (config) => new Observa(config);
+export {
+  Observa,
+  init
+};

package/dist/index.mjs

@@ -0,0 +1,63 @@
+// src/index.ts
+var Observa = class {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl || "https://api.observa.ai";
+    console.log("\u{1F4A7} Observa SDK Initialized");
+  }
+  async track(event, action) {
+    const startTime = Date.now();
+    const traceId = crypto.randomUUID();
+    const originalResponse = await action();
+    if (!originalResponse.body) return originalResponse;
+    const [stream1, stream2] = originalResponse.body.tee();
+    this.captureStream(stream2, event, traceId, startTime);
+    return new Response(stream1, {
+      headers: originalResponse.headers,
+      status: originalResponse.status,
+      statusText: originalResponse.statusText
+    });
+  }
+  async captureStream(stream, event, traceId, startTime) {
+    try {
+      const reader = stream.getReader();
+      const decoder = new TextDecoder();
+      let fullResponse = "";
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        fullResponse += decoder.decode(value, { stream: true });
+      }
+      const latency = Date.now() - startTime;
+      await this.sendTrace({
+        traceId,
+        ...event,
+        response: fullResponse,
+        latency
+      });
+    } catch (err) {
+      console.error("[Raindrop] Error capturing stream:", err);
+    }
+  }
+  async sendTrace(payload) {
+    try {
+      await fetch(`${this.baseUrl}/v1/traces`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify(payload)
+      });
+    } catch (e) {
+      console.error("[Raindrop] Failed to send trace");
+    }
+  }
+};
+var init = (config) => new Observa(config);
+export {
+  Observa,
+  init
+};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "observa-sdk",
+  "version": "0.0.1",
+  "description": "Enterprise-grade observability SDK for AI applications. Track and monitor LLM interactions with zero friction.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "observability",
+    "llm",
+    "ai",
+    "observa",
+    "monitoring",
+    "tracing",
+    "analytics"
+  ],
+  "author": "Nicka",
+  "license": "MIT"
+}