lupislabs 1.0.0

package/README.md

@@ -0,0 +1,476 @@
+# Lupis JavaScript SDK
+
+[![npm version](https://badge.fury.io/js/%40lupislabs%2Fjs-sdk.svg)](https://badge.fury.io/js/%40lupislabs%2Fjs-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A pure OpenTelemetry-based SDK for tracing HTTP requests in JavaScript applications with automatic instrumentation.
+
+## ✨ Features
+
+- 🔭 **OpenTelemetry Native** - Uses official OpenTelemetry auto-instrumentation
+- 🚀 **Zero Manual Patching** - Automatic HTTP/fetch interception
+- 📊 **OTLP Export** - Standard protocol for any observability backend
+- 💬 **Conversation Grouping** - Group related requests with chatId
+- 🎯 **Smart Provider Detection** - Automatically detects AI providers (OpenAI, Claude, etc.)
+- 📝 **Full Request/Response Capture** - Automatically captures request & response bodies, headers, and status (extends OpenTelemetry's capabilities)
+- 🔄 **No Conflicts** - Works alongside other OpenTelemetry instrumentation
+- ⚡ **Lightweight** - Clean, minimal codebase
+
+## 📦 Installation
+
+```bash
+npm install @lupislabs/js-sdk
+```
+
+## 🚀 Quick Start
+
+```javascript
+import LupisSDK from '@lupislabs/js-sdk';
+
+const sdk = new LupisSDK({
+  projectId: 'your-project-id',
+  otlpEndpoint: 'http://localhost:3010/v1/traces',
+});
+
+await sdk.run(async () => {
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Authorization': `Bearer ${API_KEY}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: 'Hello!' }],
+    }),
+  });
+  
+  return await response.json();
+}, { chatId: 'conversation-123' });
+```
+
+## 📝 Request & Response Capture
+
+Unlike standard OpenTelemetry implementations that only capture metadata, Lupis SDK automatically captures full request and response bodies, headers, and status codes. This is achieved through a custom `ResponseCaptureProcessor` that extends OpenTelemetry's capabilities.
+
+### What Gets Captured
+
+**Request Data:**
+
+- Request body (JSON, text, etc.)
+- Request headers
+- HTTP method and URL
+
+**Response Data:**
+
+- Response body (full content)
+- Response headers
+- HTTP status code
+- Response timing
+
+### How It Works
+
+The SDK uses a custom span processor that:
+
+1. Intercepts the fetch API at the earliest point
+2. Captures request data before the request is sent
+3. Clones and reads the response body without affecting the original response
+4. Attaches all data to the OpenTelemetry span as attributes
+
+### Example
+
+```javascript
+await sdk.run(async () => {
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${API_KEY}`,
+    },
+    body: JSON.stringify({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: 'Hello!' }],
+    }),
+  });
+  
+  const data = await response.json();
+}, { chatId: 'my-conversation' });
+```
+
+The span will automatically include:
+
+- `http.request.body` - The full request payload
+- `http.request.headers` - All request headers (as JSON string)
+- `http.response.body` - The complete response body
+- `http.response.headers` - All response headers (as JSON string)
+- `http.response.status` - HTTP status code (e.g., 200, 404, 500)
+
+See `examples/response-capture-example.js` for more detailed examples.
+
+## 📖 Configuration
+
+```typescript
+interface LupisConfig {
+  projectId: string;           // Required: Your project identifier
+  enabled?: boolean;           // Default: true
+  otlpEndpoint?: string;       // Default: 'http://localhost:4318/v1/traces'
+  serviceName?: string;        // Default: 'lupis-sdk'
+  serviceVersion?: string;     // Default: '1.0.0'
+}
+
+const sdk = new LupisSDK(config);
+```
+
+## 🔭 OpenTelemetry Integration
+
+This SDK uses **pure OpenTelemetry** with automatic instrumentation:
+
+- **Browser**: `@opentelemetry/instrumentation-fetch` auto-instruments `fetch()`
+- **Node.js**: `@opentelemetry/instrumentation-http` auto-instruments `http` and `https`
+
+### Features
+
+✅ **Automatic span creation** for all HTTP requests  
+✅ **Semantic conventions** (http.method, http.url, http.status_code)  
+✅ **W3C Trace Context** propagation  
+✅ **OTLP export** to any backend (Jaeger, Tempo, Datadog, etc.)  
+✅ **Custom attributes** (projectId, chatId, provider)  
+
+### Architecture
+
+```
+HTTP Request (fetch/http)
+    ↓
+Custom Fetch Patch (captures request/response data)
+    ↓
+OpenTelemetry Auto-Instrumentation
+    ├─ FetchInstrumentation (browser)
+    └─ HttpInstrumentation (Node.js)
+    ↓
+Span Created with Attributes
+    ↓
+TracerProvider
+    ├─ ChatIdSpanProcessor (adds chatId)
+    ├─ ResponseCaptureProcessor (adds request/response bodies)
+    └─ BatchSpanProcessor + OTLPExporter
+        ↓
+    Observability Backend
+```
+
+## 📋 Usage Examples
+
+### Basic HTTP Tracing
+
+```javascript
+await sdk.run(async () => {
+  const response = await fetch('https://api.example.com/data');
+  return await response.json();
+}, { chatId: 'my-conversation' });
+```
+
+### Multiple Requests
+
+```javascript
+await sdk.run(async () => {
+  const user = await fetch('/api/user').then(r => r.json());
+  const posts = await fetch('/api/posts').then(r => r.json());
+  return { user, posts };
+}, { chatId: 'user-session-123' });
+```
+
+### AI Provider Requests
+
+```javascript
+// OpenAI
+await sdk.run(async () => {
+  const response = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: { 'Authorization': `Bearer ${API_KEY}` },
+    body: JSON.stringify({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: 'Hello!' }],
+    }),
+  });
+}, { chatId: 'openai-conversation' });
+
+// Claude
+await sdk.run(async () => {
+  const response = await fetch('https://api.anthropic.com/v1/messages', {
+    method: 'POST',
+    headers: { 'x-api-key': API_KEY },
+    body: JSON.stringify({
+      model: 'claude-3-sonnet-20240229',
+      messages: [{ role: 'user', content: 'Hello!' }],
+    }),
+  });
+}, { chatId: 'claude-conversation' });
+```
+
+### Custom Spans
+
+```javascript
+import { otel } from '@lupislabs/js-sdk';
+
+const span = sdk.createSpan('data-processing', {
+  'processing.type': 'batch',
+  'batch.size': 100,
+}, otel.SpanKind.INTERNAL);
+
+try {
+  // Your processing logic
+  span.end();
+} catch (error) {
+  span.recordException(error);
+  span.setStatus({ 
+    code: otel.SpanStatusCode.ERROR, 
+    message: error.message 
+  });
+  span.end();
+}
+```
+
+### Using OpenTelemetry API Directly
+
+```javascript
+const tracer = sdk.getTracer();
+
+const span = tracer.startSpan('custom-operation', {
+  attributes: {
+    'operation.type': 'ai-inference',
+  },
+});
+
+// Your code
+span.end();
+```
+
+## 🔌 Export to Observability Backends
+
+### Jaeger
+
+```javascript
+const sdk = new LupisSDK({
+  projectId: 'my-project',
+  otlpEndpoint: 'http://localhost:4318/v1/traces',
+});
+```
+
+### Grafana Tempo
+
+```javascript
+const sdk = new LupisSDK({
+  projectId: 'my-project',
+  otlpEndpoint: 'https://tempo.example.com/v1/traces',
+});
+```
+
+### Datadog
+
+```javascript
+const sdk = new LupisSDK({
+  projectId: 'my-project',
+  otlpEndpoint: 'https://http-intake.logs.datadoghq.com/v1/traces',
+});
+```
+
+### New Relic
+
+```javascript
+const sdk = new LupisSDK({
+  projectId: 'my-project',
+  otlpEndpoint: 'https://otlp.nr-data.net/v1/traces',
+});
+```
+
+## 💬 Conversation Grouping
+
+Group related requests with `chatId`:
+
+```javascript
+// All requests in this block will have the same chatId
+await sdk.run(async () => {
+  await fetch('/api/chat', { 
+    method: 'POST',
+    body: JSON.stringify({ message: 'Hello' })
+  });
+  await fetch('/api/chat', { 
+    method: 'POST',
+    body: JSON.stringify({ message: 'How are you?' })
+  });
+}, { chatId: 'conversation-123' });
+
+// Or set/clear chatId manually
+sdk.setChatId('conversation-123');
+// Make requests...
+sdk.clearChatId();
+```
+
+## 🏷️ Span Attributes
+
+All HTTP spans automatically include:
+
+**Standard OpenTelemetry:**
+
+- `http.method` - HTTP method (GET, POST, etc.)
+- `http.url` - Full URL
+- `http.status_code` - Response status code
+
+**Custom Lupis Attributes:**
+
+- `lupis.project.id` - Your project ID
+- `lupis.chat.id` - Conversation ID (when set)
+- `http.provider` - Detected provider (openai, claude, cohere, huggingface, google)
+
+**Request/Response Capture Attributes (Custom Extension):**
+
+- `http.request.body` - Full request body content
+- `http.request.headers` - Request headers as JSON string
+- `http.response.body` - Full response body content
+- `http.response.headers` - Response headers as JSON string
+- `http.response.status` - HTTP response status code
+
+## 🔧 API Reference
+
+### LupisSDK
+
+```typescript
+class LupisSDK {
+  constructor(config: LupisConfig)
+  
+  async run<T>(fn: () => Promise<T> | T, options?: { chatId?: string }): Promise<T>
+  
+  setChatId(chatId: string): void
+  clearChatId(): void
+  
+  getTracer(): Tracer
+  createSpan(name: string, attributes?: Attributes, spanKind?: SpanKind): Span
+  
+  async shutdown(): Promise<void>
+}
+```
+
+### Methods
+
+#### `sdk.run(fn, options)`
+
+Execute a function with automatic HTTP tracing:
+
+```typescript
+await sdk.run(async () => {
+  // Your code
+}, { chatId: 'optional-chat-id' });
+```
+
+#### `sdk.setChatId(chatId)` / `sdk.clearChatId()`
+
+Manually set/clear the chatId for subsequent requests:
+
+```typescript
+sdk.setChatId('conversation-123');
+// All requests will have this chatId
+sdk.clearChatId();
+```
+
+#### `sdk.getTracer()`
+
+Get the OpenTelemetry tracer for advanced usage:
+
+```typescript
+const tracer = sdk.getTracer();
+const span = tracer.startSpan('my-operation');
+```
+
+#### `sdk.createSpan(name, attributes, spanKind)`
+
+Create a custom span:
+
+```typescript
+const span = sdk.createSpan('operation-name', {
+  'custom.attribute': 'value',
+}, SpanKind.INTERNAL);
+```
+
+#### `sdk.shutdown()`
+
+Gracefully shutdown and flush all spans:
+
+```typescript
+await sdk.shutdown();
+```
+
+## 🎯 Provider Detection
+
+The SDK automatically detects AI providers based on URL patterns:
+
+| Provider | URL Pattern | Attribute Value |
+|----------|-------------|-----------------|
+| OpenAI | `api.openai.com` | `openai` |
+| Anthropic (Claude) | `api.anthropic.com` | `claude` |
+| Cohere | `api.cohere.ai` | `cohere` |
+| HuggingFace | `api.huggingface.co` | `huggingface` |
+| Google AI | `generativelanguage.googleapis.com` | `google` |
+| Others | - | `unknown` |
+
+## ⚙️ Best Practices
+
+### 1. Meaningful ChatIds
+
+```javascript
+// Good: Descriptive and unique
+{ chatId: 'user-login-flow-2024-03-15' }
+{ chatId: 'document-analysis-task-456' }
+
+// Avoid: Generic or unclear
+{ chatId: 'test' }
+{ chatId: '1' }
+```
+
+### 2. Always Shutdown
+
+```javascript
+process.on('SIGTERM', async () => {
+  await sdk.shutdown();
+  process.exit(0);
+});
+```
+
+### 3. Error Handling
+
+```javascript
+await sdk.run(async () => {
+  try {
+    const response = await fetch('/api/data');
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+    return await response.json();
+  } catch (error) {
+    console.error('Request failed:', error);
+    throw error;
+  }
+}, { chatId: 'error-handling-example' });
+```
+
+## 📚 Documentation
+
+- [ARCHITECTURE.md](./ARCHITECTURE.md) - Detailed architecture
+- [OPENTELEMETRY.md](./OPENTELEMETRY.md) - OpenTelemetry integration guide
+- [examples/](./examples/) - Code examples
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 📄 License
+
+This project is licensed under the MIT License.
+
+## 🆘 Support
+
+If you encounter any issues:
+1. Check the [Issues](https://github.com/lupislabs/lupis/issues) page
+2. Create a new issue with detailed information
+
+---
+
+**Made with ❤️ by the Lupis team**

package/dist/http-interceptor.d.ts

@@ -0,0 +1,23 @@
+import * as api from '@opentelemetry/api';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { WebTracerProvider } from '@opentelemetry/sdk-trace-web';
+export declare class HttpInterceptor {
+    private originalFetch?;
+    private originalHttpRequest?;
+    private originalHttpsRequest?;
+    private tracer;
+    private provider;
+    private projectId;
+    private isIntercepting;
+    private zlib?;
+    constructor(tracer: api.Tracer, provider: NodeTracerProvider | WebTracerProvider, projectId: string);
+    startIntercepting(): void;
+    stopIntercepting(): void;
+    private patchFetch;
+    private patchNodeHttp;
+    private detectProvider;
+    private resolveHandler;
+    private getRawResponseText;
+    private decompressIfNeeded;
+}
+//# sourceMappingURL=http-interceptor.d.ts.map

package/dist/http-interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-interceptor.d.ts","sourceRoot":"","sources":["../src/http-interceptor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,GAAG,MAAM,oBAAoB,CAAC;AAC1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAMjE,qBAAa,eAAe;IAC1B,OAAO,CAAC,aAAa,CAAC,CAAe;IACrC,OAAO,CAAC,mBAAmB,CAAC,CAAM;IAClC,OAAO,CAAC,oBAAoB,CAAC,CAAM;IACnC,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,QAAQ,CAAyC;IACzD,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,cAAc,CAAkB;IACxC,OAAO,CAAC,IAAI,CAAC,CAAM;gBAEP,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,kBAAkB,GAAG,iBAAiB,EAAE,SAAS,EAAE,MAAM;IAMnG,iBAAiB;IAUjB,gBAAgB;IAsBhB,OAAO,CAAC,UAAU;IA+LlB,OAAO,CAAC,aAAa;IAsKrB,OAAO,CAAC,cAAc;IAStB,OAAO,CAAC,cAAc;YAYR,kBAAkB;IAShC,OAAO,CAAC,kBAAkB;CA4B3B"}