@lelemondev/sdk 0.4.0 → 0.5.0

package/README.md

@@ -6,6 +6,13 @@
 
 Automatic LLM observability for Node.js. Wrap your client, everything is traced.
 
+## LLM Agent Docs
+
+```
+https://lelemondev.github.io/lelemondev-sdk/llms.txt
+https://lelemondev.github.io/lelemondev-sdk/llms-full.txt
+```
+
 ## Features
 
 - **Automatic Tracing** - Wrap your client, all calls are traced
@@ -39,8 +46,150 @@ const response = await openai.chat.completions.create({
 });
 ```
 
+## Supported Providers
+
+| Provider | Status | Methods |
+|----------|--------|---------|
+| OpenAI | ✅ | `chat.completions.create()`, `responses.create()`, `completions.create()`, `embeddings.create()` |
+| OpenRouter | ✅ | `chat.completions.create()` (access to 400+ models) |
+| Anthropic | ✅ | `messages.create()`, `messages.stream()` |
+| AWS Bedrock | ✅ | `ConverseCommand`, `ConverseStreamCommand`, `InvokeModelCommand` |
+| Google Gemini | ✅ | `generateContent()`, `generateContentStream()`, `chat.sendMessage()` |
+
+### OpenRouter
+
+[OpenRouter](https://openrouter.ai) provides unified access to 400+ models from OpenAI, Anthropic, Google, Meta, Mistral, and more through a single API.
+
+```typescript
+import { init, observe } from '@lelemondev/sdk';
+import OpenAI from 'openai';
+
+init({ apiKey: process.env.LELEMON_API_KEY });
+
+// Configure OpenAI SDK to use OpenRouter
+const openrouter = observe(new OpenAI({
+  baseURL: 'https://openrouter.ai/api/v1',
+  apiKey: process.env.OPENROUTER_API_KEY,
+  defaultHeaders: {
+    'HTTP-Referer': 'https://your-app.com', // Optional: for OpenRouter rankings
+    'X-Title': 'Your App Name',             // Optional: for OpenRouter rankings
+  },
+}));
+
+// Access any model through OpenRouter
+const response = await openrouter.chat.completions.create({
+  model: 'anthropic/claude-3-opus',  // or 'openai/gpt-4', 'google/gemini-pro', etc.
+  messages: [{ role: 'user', content: 'Hello!' }],
+});
+```
+
+Models are specified in `provider/model` format (e.g., `anthropic/claude-3-opus`, `openai/gpt-4`, `meta-llama/llama-3-70b`). See [OpenRouter Models](https://openrouter.ai/models) for the full list.
+
+## Usage Without Framework Integrations
+
+The SDK works with **any Node.js application**. Framework integrations are optional - they just automate the `flush()` call.
+
+### Long-running Processes (Servers, Workers)
+
+For long-running processes, the SDK auto-flushes every second (configurable via `flushIntervalMs`):
+
+```typescript
+import { init, observe } from '@lelemondev/sdk';
+import OpenAI from 'openai';
+
+init({ apiKey: process.env.LELEMON_API_KEY });
+const openai = observe(new OpenAI());
+
+// In your HTTP server, WebSocket handler, queue worker, etc.
+async function handleRequest(userId: string, message: string) {
+  const client = observe(new OpenAI(), { userId });
+
+  const result = await client.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: message }],
+  });
+
+  return result.choices[0].message;
+  // Traces are auto-flushed in the background (every 1s by default)
+}
+```
+
+### Short-lived Processes (Scripts, Serverless, CLI)
+
+For scripts or serverless functions, call `flush()` before the process exits:
+
+```typescript
+import { init, observe, flush } from '@lelemondev/sdk';
+import OpenAI from 'openai';
+
+init({ apiKey: process.env.LELEMON_API_KEY });
+const openai = observe(new OpenAI());
+
+async function main() {
+  const result = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: 'Hello!' }],
+  });
+
+  console.log(result.choices[0].message.content);
+
+  // IMPORTANT: Flush before exit to ensure traces are sent
+  await flush();
+}
+
+main();
+```
+
+### Custom HTTP Server (No Framework)
+
+```typescript
+import http from 'http';
+import { init, observe, flush } from '@lelemondev/sdk';
+import OpenAI from 'openai';
+
+init({ apiKey: process.env.LELEMON_API_KEY });
+
+const server = http.createServer(async (req, res) => {
+  if (req.method === 'POST' && req.url === '/chat') {
+    const openai = observe(new OpenAI(), {
+      userId: req.headers['x-user-id'] as string,
+    });
+
+    const result = await openai.chat.completions.create({
+      model: 'gpt-4',
+      messages: [{ role: 'user', content: 'Hello!' }],
+    });
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(result.choices[0].message));
+    // Auto-flush handles this in background
+  }
+});
+
+// Graceful shutdown - flush remaining traces
+process.on('SIGTERM', async () => {
+  await flush();
+  server.close();
+});
+
+server.listen(3000);
+```
+
+### When to Use Framework Integrations vs Manual
+
+| Scenario | Recommendation |
+|----------|----------------|
+| Next.js, Express, Hono, Lambda | Use framework integration (auto-flush) |
+| Custom HTTP server | Auto-flush works, add `flush()` on shutdown |
+| CLI scripts | Always call `flush()` before exit |
+| Background workers (Bull, BullMQ) | Auto-flush works, add `flush()` on shutdown |
+| One-off scripts | Always call `flush()` before exit |
+| Long-running daemons | Auto-flush works |
+
 ## Framework Integrations
 
+Framework integrations automate the `flush()` call so you don't have to think about it.
+
 ### Next.js App Router
 
 ```typescript
@@ -138,13 +287,6 @@ app.post('/chat', async (c) => {
 export default app;
 ```
 
-## Supported Providers
-
-| Provider | Status | Methods |
-|----------|--------|---------|
-| OpenAI | Supported | `chat.completions.create()`, `completions.create()`, `embeddings.create()` |
-| Anthropic | Supported | `messages.create()`, `messages.stream()` |
-
 ## API Reference
 
 ### `init(config)`
@@ -183,9 +325,295 @@ Manually flush pending traces. Use in serverless without framework integration.
 await flush();
 ```
 
+## User & Session Tracking
+
+Track which user generated each trace and group related conversations.
+
+### Available Fields
+
+| Field | Purpose | In Dashboard |
+|-------|---------|--------------|
+| `userId` | Identify the end user | Shown in "User" column, searchable |
+| `sessionId` | Group related traces (e.g., a conversation) | Shown in "Session" column, searchable |
+| `metadata` | Custom data attached to the trace | Visible in trace detail view |
+| `tags` | Labels for categorization | Shown as badges, filterable dropdown |
+
+#### Field Details
+
+**`userId`** - Identifies who made the request
+```typescript
+userId: req.user.id           // From your auth system
+userId: 'user-123'            // Any string identifier
+userId: req.user.email        // Email works too
+```
+
+**`sessionId`** - Groups multiple calls into one conversation/session
+```typescript
+sessionId: req.body.conversationId   // Chat conversation ID
+sessionId: req.headers['x-session-id'] // From client header
+sessionId: crypto.randomUUID()        // Generate per session
+```
+
+**`metadata`** - Any extra data you want to attach (stored as JSON)
+```typescript
+metadata: {
+  plan: 'premium',           // User's subscription plan
+  feature: 'chat',           // Which feature triggered this
+  version: '2.1.0',          // Your app version
+  environment: 'production', // Environment
+  ip: req.ip,                // Client IP (for debugging)
+  customField: 'any value',  // Anything you need
+}
+```
+
+**`tags`** - Quick labels for filtering (array of strings)
+```typescript
+tags: ['production']                    // Environment
+tags: ['chat', 'premium']               // Feature + plan
+tags: ['api', 'v2']                     // Service + version
+tags: [tenantId, 'high-priority']       // Multi-tenant + priority
+```
+
+### Basic Usage
+
+```typescript
+const openai = observe(new OpenAI(), {
+  userId: 'user-123',
+  sessionId: 'conversation-abc',
+});
+```
+
+### In an API Endpoint
+
+```typescript
+// Express
+app.post('/chat', async (req, res) => {
+  // Create client with user context from the request
+  const openai = observe(new OpenAI(), {
+    userId: req.user.id,
+    sessionId: req.headers['x-session-id'],
+    metadata: {
+      plan: req.user.plan,
+      endpoint: '/chat'
+    },
+  });
+
+  const result = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: req.body.message }],
+  });
+
+  res.json(result.choices[0].message);
+});
+```
+
+### Reusable Context with createObserve()
+
+When you have multiple LLM clients or make calls from different places, use `createObserve()` to avoid repeating context:
+
+```typescript
+import { createObserve } from '@lelemondev/sdk';
+import OpenAI from 'openai';
+import { GoogleGenerativeAI } from '@google/generative-ai';
+import { BedrockRuntimeClient } from '@aws-sdk/client-bedrock-runtime';
+
+// Create a scoped observe function with user context
+const observeForUser = createObserve({
+  userId: 'user-123',
+  sessionId: 'session-456',
+  tags: ['premium'],
+});
+
+// All clients inherit the same context
+const openai = observeForUser(new OpenAI());
+const gemini = observeForUser(new GoogleGenerativeAI(apiKey));
+const bedrock = observeForUser(new BedrockRuntimeClient({}));
+
+// All these calls will be associated with user-123
+await openai.chat.completions.create({ ... });
+await gemini.getGenerativeModel({ model: 'gemini-pro' }).generateContent('...');
+```
+
+### In Middleware (Express)
+
+Set up user context once, use it everywhere:
+
+```typescript
+import { createObserve } from '@lelemondev/sdk';
+
+// Middleware to attach observe function to request
+app.use((req, res, next) => {
+  req.observe = createObserve({
+    userId: req.user?.id,
+    sessionId: req.headers['x-session-id'] || crypto.randomUUID(),
+    metadata: {
+      ip: req.ip,
+      userAgent: req.headers['user-agent'],
+    },
+  });
+  next();
+});
+
+// In any route handler
+app.post('/chat', async (req, res) => {
+  const openai = req.observe(new OpenAI());
+  // Calls are automatically associated with the user
+});
+
+app.post('/summarize', async (req, res) => {
+  const gemini = req.observe(new GoogleGenerativeAI(apiKey));
+  // Same user context, different endpoint
+});
+```
+
+### Multi-tenant Application
+
+```typescript
+app.post('/api/:tenantId/chat', async (req, res) => {
+  const openai = observe(new OpenAI(), {
+    userId: req.user.id,
+    sessionId: req.body.conversationId,
+    metadata: {
+      tenantId: req.params.tenantId,
+      environment: process.env.NODE_ENV,
+    },
+    tags: [req.params.tenantId, req.user.plan],
+  });
+
+  // Traces can be filtered by tenant, user, or conversation
+});
+```
+
+### Distributed Systems (API + WebSocket)
+
+When your application spans multiple services (REST API, WebSocket server, background workers), use consistent identifiers across all of them:
+
+```typescript
+// Shared utility for creating observe context
+// utils/observe-context.ts
+import { createObserve } from '@lelemondev/sdk';
+
+export function createUserObserve(userId: string, sessionId: string, service: string) {
+  return createObserve({
+    userId,
+    sessionId,
+    metadata: { service },
+    tags: [service],
+  });
+}
+```
+
+**REST API Server:**
+
+```typescript
+// api-server.ts
+import { createUserObserve } from './utils/observe-context';
+
+app.post('/chat/start', async (req, res) => {
+  const { userId, sessionId } = req.body;
+
+  const observe = createUserObserve(userId, sessionId, 'api');
+  const openai = observe(new OpenAI());
+
+  const result = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: req.body.message }],
+  });
+
+  res.json({
+    response: result.choices[0].message,
+    sessionId, // Return sessionId for client to use in WebSocket
+  });
+});
+```
+
+**WebSocket Server:**
+
+```typescript
+// ws-server.ts
+import { createUserObserve } from './utils/observe-context';
+
+wss.on('connection', (ws, req) => {
+  // Get userId and sessionId from connection (query params, auth token, etc.)
+  const userId = getUserFromToken(req);
+  const sessionId = new URL(req.url, 'http://localhost').searchParams.get('sessionId');
+
+  // Create observe function for this connection
+  const observe = createUserObserve(userId, sessionId, 'websocket');
+  const gemini = observe(new GoogleGenerativeAI(apiKey));
+
+  ws.on('message', async (data) => {
+    const { message } = JSON.parse(data);
+
+    // This trace will be linked to the same session as the API calls
+    const model = gemini.getGenerativeModel({ model: 'gemini-pro' });
+    const result = await model.generateContent(message);
+
+    ws.send(JSON.stringify({ response: result.response.text() }));
+  });
+});
+```
+
+**Background Worker / Queue Consumer:**
+
+```typescript
+// worker.ts
+import { createUserObserve } from './utils/observe-context';
+
+queue.process('ai-task', async (job) => {
+  const { userId, sessionId, prompt } = job.data;
+
+  const observe = createUserObserve(userId, sessionId, 'worker');
+  const bedrock = observe(new BedrockRuntimeClient({}));
+
+  const command = new ConverseCommand({
+    modelId: 'anthropic.claude-3-sonnet-20240229-v1:0',
+    messages: [{ role: 'user', content: [{ text: prompt }] }],
+  });
+
+  const result = await bedrock.send(command);
+  return result.output.message.content[0].text;
+});
+```
+
+**Client-side (passing sessionId between services):**
+
+```typescript
+// Frontend - maintains sessionId across API and WebSocket
+const sessionId = crypto.randomUUID(); // Or from your session management
+
+// REST API call
+const response = await fetch('/chat/start', {
+  method: 'POST',
+  body: JSON.stringify({ userId, sessionId, message: 'Hello' }),
+});
+
+// WebSocket connection with same sessionId
+const ws = new WebSocket(`wss://your-app.com/ws?sessionId=${sessionId}`);
+
+// Both API and WebSocket traces will be grouped under the same session
+```
+
+**Viewing in Dashboard:**
+
+With consistent `userId` and `sessionId` across services, you can:
+- See a user's complete journey across API → WebSocket → Background jobs
+- Filter by service (`metadata.service`) to isolate issues
+- Track a conversation that spans multiple services
+
+### What This Enables
+
+With proper user/session tracking you can:
+
+- **Filter traces by user** - See all LLM calls from a specific user
+- **View full conversations** - Group all calls in a session together
+- **Debug issues** - Find exactly what happened for a specific user request
+- **Analyze usage patterns** - Understand how different user segments use your AI features
+- **Cost attribution** - Track token usage per user, tenant, or feature
+
 ## Streaming
 
-Both OpenAI and Anthropic streaming are fully supported:
+All providers support streaming:
 
 ```typescript
 const stream = await openai.chat.completions.create({
@@ -204,8 +632,8 @@ for await (const chunk of stream) {
 
 Each LLM call automatically captures:
 
-- **Provider** - openai, anthropic
-- **Model** - gpt-4, claude-3-opus, etc.
+- **Provider** - openai, anthropic, bedrock, gemini
+- **Model** - gpt-4, claude-3-opus, gemini-pro, etc.
 - **Input** - Messages/prompt (sanitized)
 - **Output** - Response content
 - **Tokens** - Input and output counts

package/dist/{express-Cmb_A4sI.d.mts → express-Dt5wT6_n.d.mts}

@@ -10,15 +10,31 @@
  * const app = express();
  * app.use(createMiddleware());
  */
+/**
+ * Minimal Express request type (avoids requiring express as dependency)
+ */
 interface ExpressRequest {
     [key: string]: unknown;
 }
+/**
+ * Minimal Express response type (avoids requiring express as dependency)
+ */
 interface ExpressResponse {
     on(event: 'finish' | 'close' | 'error', listener: () => void): this;
     [key: string]: unknown;
 }
-type NextFunction = (error?: unknown) => void;
-type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => void;
+/**
+ * Express next function type
+ */
+type ExpressNextFunction = (error?: unknown) => void;
+/**
+ * Express middleware function type
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Next function to pass control
+ */
+type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
 /**
  * Create Express middleware for automatic trace flushing
  *
@@ -39,9 +55,13 @@ type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: NextF
  */
 declare function createMiddleware(): ExpressMiddleware;
 
+type express_ExpressMiddleware = ExpressMiddleware;
+type express_ExpressNextFunction = ExpressNextFunction;
+type express_ExpressRequest = ExpressRequest;
+type express_ExpressResponse = ExpressResponse;
 declare const express_createMiddleware: typeof createMiddleware;
 declare namespace express {
-  export { express_createMiddleware as createMiddleware };
+  export { type express_ExpressMiddleware as ExpressMiddleware, type express_ExpressNextFunction as ExpressNextFunction, type express_ExpressRequest as ExpressRequest, type express_ExpressResponse as ExpressResponse, express_createMiddleware as createMiddleware };
 }
 
-export { createMiddleware as c, express as e };
+export { type ExpressRequest as E, type ExpressResponse as a, type ExpressNextFunction as b, type ExpressMiddleware as c, createMiddleware as d, express as e };

package/dist/{express-Cmb_A4sI.d.ts → express-Dt5wT6_n.d.ts}

@@ -10,15 +10,31 @@
  * const app = express();
  * app.use(createMiddleware());
  */
+/**
+ * Minimal Express request type (avoids requiring express as dependency)
+ */
 interface ExpressRequest {
     [key: string]: unknown;
 }
+/**
+ * Minimal Express response type (avoids requiring express as dependency)
+ */
 interface ExpressResponse {
     on(event: 'finish' | 'close' | 'error', listener: () => void): this;
     [key: string]: unknown;
 }
-type NextFunction = (error?: unknown) => void;
-type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => void;
+/**
+ * Express next function type
+ */
+type ExpressNextFunction = (error?: unknown) => void;
+/**
+ * Express middleware function type
+ *
+ * @param req - Express request object
+ * @param res - Express response object
+ * @param next - Next function to pass control
+ */
+type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: ExpressNextFunction) => void;
 /**
  * Create Express middleware for automatic trace flushing
  *
@@ -39,9 +55,13 @@ type ExpressMiddleware = (req: ExpressRequest, res: ExpressResponse, next: NextF
  */
 declare function createMiddleware(): ExpressMiddleware;
 
+type express_ExpressMiddleware = ExpressMiddleware;
+type express_ExpressNextFunction = ExpressNextFunction;
+type express_ExpressRequest = ExpressRequest;
+type express_ExpressResponse = ExpressResponse;
 declare const express_createMiddleware: typeof createMiddleware;
 declare namespace express {
-  export { express_createMiddleware as createMiddleware };
+  export { type express_ExpressMiddleware as ExpressMiddleware, type express_ExpressNextFunction as ExpressNextFunction, type express_ExpressRequest as ExpressRequest, type express_ExpressResponse as ExpressResponse, express_createMiddleware as createMiddleware };
 }
 
-export { createMiddleware as c, express as e };
+export { type ExpressRequest as E, type ExpressResponse as a, type ExpressNextFunction as b, type ExpressMiddleware as c, createMiddleware as d, express as e };

package/dist/express.d.mts

@@ -1 +1 @@
-export { c as createMiddleware } from './express-Cmb_A4sI.mjs';
+export { c as ExpressMiddleware, b as ExpressNextFunction, E as ExpressRequest, a as ExpressResponse, d as createMiddleware } from './express-Dt5wT6_n.mjs';

package/dist/express.d.ts

@@ -1 +1 @@
-export { c as createMiddleware } from './express-Cmb_A4sI.js';
+export { c as ExpressMiddleware, b as ExpressNextFunction, E as ExpressRequest, a as ExpressResponse, d as createMiddleware } from './express-Dt5wT6_n.js';

package/dist/express.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/config.ts","../src/integrations/express.ts"],"names":[],"mappings":";;;;AAuEA,eAAsB,KAAA,GAAuB;AAI7C;;;ACjBO,SAAS,gBAAA,GAAsC;AACpD,EAAA,OAAO,CAAC,IAAA,EAAM,GAAA,EAAK,IAAA,KAAS;AAE1B,IAAA,GAAA,CAAI,EAAA,CAAG,UAAU,MAAM;AACrB,MAAA,KAAA,EAAM,CAAE,MAAM,MAAM;AAAA,MAEpB,CAAC,CAAA;AAAA,IACH,CAAC,CAAA;AAED,IAAA,IAAA,EAAK;AAAA,EACP,CAAA;AACF","file":"express.js","sourcesContent":["/**\n * Global Configuration\n *\n * Manages SDK configuration and transport instance.\n */\n\nimport type { LelemonConfig } from './types';\nimport { Transport } from './transport';\n\n// ─────────────────────────────────────────────────────────────\n// Global State\n// ─────────────────────────────────────────────────────────────\n\nlet globalConfig: LelemonConfig = {};\nlet globalTransport: Transport | null = null;\nlet initialized = false;\n\n// ─────────────────────────────────────────────────────────────\n// Configuration\n// ─────────────────────────────────────────────────────────────\n\nconst DEFAULT_ENDPOINT = 'https://api.lelemon.dev';\n\n/**\n * Initialize the SDK\n * Call once at app startup\n */\nexport function init(config: LelemonConfig = {}): void {\n  globalConfig = config;\n  globalTransport = createTransport(config);\n  initialized = true;\n}\n\n/**\n * Get current config\n */\nexport function getConfig(): LelemonConfig {\n  return globalConfig;\n}\n\n/**\n * Check if SDK is initialized\n */\nexport function isInitialized(): boolean {\n  return initialized;\n}\n\n/**\n * Check if SDK is enabled\n */\nexport function isEnabled(): boolean {\n  return getTransport().isEnabled();\n}\n\n// ─────────────────────────────────────────────────────────────\n// Transport\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Get or create transport instance\n */\nexport function getTransport(): Transport {\n  if (!globalTransport) {\n    globalTransport = createTransport(globalConfig);\n  }\n  return globalTransport;\n}\n\n/**\n * Flush all pending traces\n */\nexport async function flush(): Promise<void> {\n  if (globalTransport) {\n    await globalTransport.flush();\n  }\n}\n\n/**\n * Create transport instance\n */\nfunction createTransport(config: LelemonConfig): Transport {\n  const apiKey = config.apiKey ?? getEnvVar('LELEMON_API_KEY');\n\n  if (!apiKey && !config.disabled) {\n    console.warn(\n      '[Lelemon] No API key provided. Set apiKey in init() or LELEMON_API_KEY env var. Tracing disabled.'\n    );\n  }\n\n  return new Transport({\n    apiKey: apiKey ?? '',\n    endpoint: config.endpoint ?? DEFAULT_ENDPOINT,\n    debug: config.debug ?? false,\n    disabled: config.disabled ?? !apiKey,\n    batchSize: config.batchSize,\n    flushIntervalMs: config.flushIntervalMs,\n    requestTimeoutMs: config.requestTimeoutMs,\n  });\n}\n\n/**\n * Get environment variable (works in Node and edge)\n */\nfunction getEnvVar(name: string): string | undefined {\n  if (typeof process !== 'undefined' && process.env) {\n    return process.env[name];\n  }\n  return undefined;\n}\n","/**\n * Express Integration\n *\n * Middleware that automatically flushes traces when response finishes.\n *\n * @example\n * import express from 'express';\n * import { createMiddleware } from '@lelemondev/sdk/express';\n *\n * const app = express();\n * app.use(createMiddleware());\n */\n\nimport { flush } from '../core/config';\n\n// ─────────────────────────────────────────────────────────────\n// Types (minimal to avoid requiring express as dependency)\n// ─────────────────────────────────────────────────────────────\n\ninterface ExpressRequest {\n  [key: string]: unknown;\n}\n\ninterface ExpressResponse {\n  on(event: 'finish' | 'close' | 'error', listener: () => void): this;\n  [key: string]: unknown;\n}\n\ntype NextFunction = (error?: unknown) => void;\n\ntype ExpressMiddleware = (\n  req: ExpressRequest,\n  res: ExpressResponse,\n  next: NextFunction\n) => void;\n\n// ─────────────────────────────────────────────────────────────\n// Middleware\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Create Express middleware for automatic trace flushing\n *\n * Flushes traces when the response finishes (after res.send/res.json).\n * This is fire-and-forget and doesn't block the response.\n *\n * @returns Express middleware function\n *\n * @example\n * // Global middleware\n * app.use(createMiddleware());\n *\n * @example\n * // Per-route middleware\n * app.post('/chat', createMiddleware(), async (req, res) => {\n *   res.json({ ok: true });\n * });\n */\nexport function createMiddleware(): ExpressMiddleware {\n  return (_req, res, next) => {\n    // Flush when response is finished (after headers + body sent)\n    res.on('finish', () => {\n      flush().catch(() => {\n        // Silently ignore flush errors - fire and forget\n      });\n    });\n\n    next();\n  };\n}\n"]}
+{"version":3,"sources":["../src/core/config.ts","../src/integrations/express.ts"],"names":[],"mappings":";;;;AAuEA,eAAsB,KAAA,GAAuB;AAI7C;;;ACDO,SAAS,gBAAA,GAAsC;AACpD,EAAA,OAAO,CAAC,IAAA,EAAM,GAAA,EAAK,IAAA,KAAS;AAE1B,IAAA,GAAA,CAAI,EAAA,CAAG,UAAU,MAAM;AACrB,MAAA,KAAA,EAAM,CAAE,MAAM,MAAM;AAAA,MAEpB,CAAC,CAAA;AAAA,IACH,CAAC,CAAA;AAED,IAAA,IAAA,EAAK;AAAA,EACP,CAAA;AACF","file":"express.js","sourcesContent":["/**\n * Global Configuration\n *\n * Manages SDK configuration and transport instance.\n */\n\nimport type { LelemonConfig } from './types';\nimport { Transport } from './transport';\n\n// ─────────────────────────────────────────────────────────────\n// Global State\n// ─────────────────────────────────────────────────────────────\n\nlet globalConfig: LelemonConfig = {};\nlet globalTransport: Transport | null = null;\nlet initialized = false;\n\n// ─────────────────────────────────────────────────────────────\n// Configuration\n// ─────────────────────────────────────────────────────────────\n\nconst DEFAULT_ENDPOINT = 'https://api.lelemon.dev';\n\n/**\n * Initialize the SDK\n * Call once at app startup\n */\nexport function init(config: LelemonConfig = {}): void {\n  globalConfig = config;\n  globalTransport = createTransport(config);\n  initialized = true;\n}\n\n/**\n * Get current config\n */\nexport function getConfig(): LelemonConfig {\n  return globalConfig;\n}\n\n/**\n * Check if SDK is initialized\n */\nexport function isInitialized(): boolean {\n  return initialized;\n}\n\n/**\n * Check if SDK is enabled\n */\nexport function isEnabled(): boolean {\n  return getTransport().isEnabled();\n}\n\n// ─────────────────────────────────────────────────────────────\n// Transport\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Get or create transport instance\n */\nexport function getTransport(): Transport {\n  if (!globalTransport) {\n    globalTransport = createTransport(globalConfig);\n  }\n  return globalTransport;\n}\n\n/**\n * Flush all pending traces\n */\nexport async function flush(): Promise<void> {\n  if (globalTransport) {\n    await globalTransport.flush();\n  }\n}\n\n/**\n * Create transport instance\n */\nfunction createTransport(config: LelemonConfig): Transport {\n  const apiKey = config.apiKey ?? getEnvVar('LELEMON_API_KEY');\n\n  if (!apiKey && !config.disabled) {\n    console.warn(\n      '[Lelemon] No API key provided. Set apiKey in init() or LELEMON_API_KEY env var. Tracing disabled.'\n    );\n  }\n\n  return new Transport({\n    apiKey: apiKey ?? '',\n    endpoint: config.endpoint ?? DEFAULT_ENDPOINT,\n    debug: config.debug ?? false,\n    disabled: config.disabled ?? !apiKey,\n    batchSize: config.batchSize,\n    flushIntervalMs: config.flushIntervalMs,\n    requestTimeoutMs: config.requestTimeoutMs,\n  });\n}\n\n/**\n * Get environment variable (works in Node and edge)\n */\nfunction getEnvVar(name: string): string | undefined {\n  if (typeof process !== 'undefined' && process.env) {\n    return process.env[name];\n  }\n  return undefined;\n}\n","/**\n * Express Integration\n *\n * Middleware that automatically flushes traces when response finishes.\n *\n * @example\n * import express from 'express';\n * import { createMiddleware } from '@lelemondev/sdk/express';\n *\n * const app = express();\n * app.use(createMiddleware());\n */\n\nimport { flush } from '../core/config';\n\n// ─────────────────────────────────────────────────────────────\n// Types (minimal to avoid requiring express as dependency)\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Minimal Express request type (avoids requiring express as dependency)\n */\nexport interface ExpressRequest {\n  [key: string]: unknown;\n}\n\n/**\n * Minimal Express response type (avoids requiring express as dependency)\n */\nexport interface ExpressResponse {\n  on(event: 'finish' | 'close' | 'error', listener: () => void): this;\n  [key: string]: unknown;\n}\n\n/**\n * Express next function type\n */\nexport type ExpressNextFunction = (error?: unknown) => void;\n\n/**\n * Express middleware function type\n *\n * @param req - Express request object\n * @param res - Express response object\n * @param next - Next function to pass control\n */\nexport type ExpressMiddleware = (\n  req: ExpressRequest,\n  res: ExpressResponse,\n  next: ExpressNextFunction\n) => void;\n\n// ─────────────────────────────────────────────────────────────\n// Middleware\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Create Express middleware for automatic trace flushing\n *\n * Flushes traces when the response finishes (after res.send/res.json).\n * This is fire-and-forget and doesn't block the response.\n *\n * @returns Express middleware function\n *\n * @example\n * // Global middleware\n * app.use(createMiddleware());\n *\n * @example\n * // Per-route middleware\n * app.post('/chat', createMiddleware(), async (req, res) => {\n *   res.json({ ok: true });\n * });\n */\nexport function createMiddleware(): ExpressMiddleware {\n  return (_req, res, next) => {\n    // Flush when response is finished (after headers + body sent)\n    res.on('finish', () => {\n      flush().catch(() => {\n        // Silently ignore flush errors - fire and forget\n      });\n    });\n\n    next();\n  };\n}\n"]}

package/dist/express.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/core/config.ts","../src/integrations/express.ts"],"names":[],"mappings":";;AAuEA,eAAsB,KAAA,GAAuB;AAI7C;;;ACjBO,SAAS,gBAAA,GAAsC;AACpD,EAAA,OAAO,CAAC,IAAA,EAAM,GAAA,EAAK,IAAA,KAAS;AAE1B,IAAA,GAAA,CAAI,EAAA,CAAG,UAAU,MAAM;AACrB,MAAA,KAAA,EAAM,CAAE,MAAM,MAAM;AAAA,MAEpB,CAAC,CAAA;AAAA,IACH,CAAC,CAAA;AAED,IAAA,IAAA,EAAK;AAAA,EACP,CAAA;AACF","file":"express.mjs","sourcesContent":["/**\n * Global Configuration\n *\n * Manages SDK configuration and transport instance.\n */\n\nimport type { LelemonConfig } from './types';\nimport { Transport } from './transport';\n\n// ─────────────────────────────────────────────────────────────\n// Global State\n// ─────────────────────────────────────────────────────────────\n\nlet globalConfig: LelemonConfig = {};\nlet globalTransport: Transport | null = null;\nlet initialized = false;\n\n// ─────────────────────────────────────────────────────────────\n// Configuration\n// ─────────────────────────────────────────────────────────────\n\nconst DEFAULT_ENDPOINT = 'https://api.lelemon.dev';\n\n/**\n * Initialize the SDK\n * Call once at app startup\n */\nexport function init(config: LelemonConfig = {}): void {\n  globalConfig = config;\n  globalTransport = createTransport(config);\n  initialized = true;\n}\n\n/**\n * Get current config\n */\nexport function getConfig(): LelemonConfig {\n  return globalConfig;\n}\n\n/**\n * Check if SDK is initialized\n */\nexport function isInitialized(): boolean {\n  return initialized;\n}\n\n/**\n * Check if SDK is enabled\n */\nexport function isEnabled(): boolean {\n  return getTransport().isEnabled();\n}\n\n// ─────────────────────────────────────────────────────────────\n// Transport\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Get or create transport instance\n */\nexport function getTransport(): Transport {\n  if (!globalTransport) {\n    globalTransport = createTransport(globalConfig);\n  }\n  return globalTransport;\n}\n\n/**\n * Flush all pending traces\n */\nexport async function flush(): Promise<void> {\n  if (globalTransport) {\n    await globalTransport.flush();\n  }\n}\n\n/**\n * Create transport instance\n */\nfunction createTransport(config: LelemonConfig): Transport {\n  const apiKey = config.apiKey ?? getEnvVar('LELEMON_API_KEY');\n\n  if (!apiKey && !config.disabled) {\n    console.warn(\n      '[Lelemon] No API key provided. Set apiKey in init() or LELEMON_API_KEY env var. Tracing disabled.'\n    );\n  }\n\n  return new Transport({\n    apiKey: apiKey ?? '',\n    endpoint: config.endpoint ?? DEFAULT_ENDPOINT,\n    debug: config.debug ?? false,\n    disabled: config.disabled ?? !apiKey,\n    batchSize: config.batchSize,\n    flushIntervalMs: config.flushIntervalMs,\n    requestTimeoutMs: config.requestTimeoutMs,\n  });\n}\n\n/**\n * Get environment variable (works in Node and edge)\n */\nfunction getEnvVar(name: string): string | undefined {\n  if (typeof process !== 'undefined' && process.env) {\n    return process.env[name];\n  }\n  return undefined;\n}\n","/**\n * Express Integration\n *\n * Middleware that automatically flushes traces when response finishes.\n *\n * @example\n * import express from 'express';\n * import { createMiddleware } from '@lelemondev/sdk/express';\n *\n * const app = express();\n * app.use(createMiddleware());\n */\n\nimport { flush } from '../core/config';\n\n// ─────────────────────────────────────────────────────────────\n// Types (minimal to avoid requiring express as dependency)\n// ─────────────────────────────────────────────────────────────\n\ninterface ExpressRequest {\n  [key: string]: unknown;\n}\n\ninterface ExpressResponse {\n  on(event: 'finish' | 'close' | 'error', listener: () => void): this;\n  [key: string]: unknown;\n}\n\ntype NextFunction = (error?: unknown) => void;\n\ntype ExpressMiddleware = (\n  req: ExpressRequest,\n  res: ExpressResponse,\n  next: NextFunction\n) => void;\n\n// ─────────────────────────────────────────────────────────────\n// Middleware\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Create Express middleware for automatic trace flushing\n *\n * Flushes traces when the response finishes (after res.send/res.json).\n * This is fire-and-forget and doesn't block the response.\n *\n * @returns Express middleware function\n *\n * @example\n * // Global middleware\n * app.use(createMiddleware());\n *\n * @example\n * // Per-route middleware\n * app.post('/chat', createMiddleware(), async (req, res) => {\n *   res.json({ ok: true });\n * });\n */\nexport function createMiddleware(): ExpressMiddleware {\n  return (_req, res, next) => {\n    // Flush when response is finished (after headers + body sent)\n    res.on('finish', () => {\n      flush().catch(() => {\n        // Silently ignore flush errors - fire and forget\n      });\n    });\n\n    next();\n  };\n}\n"]}
+{"version":3,"sources":["../src/core/config.ts","../src/integrations/express.ts"],"names":[],"mappings":";;AAuEA,eAAsB,KAAA,GAAuB;AAI7C;;;ACDO,SAAS,gBAAA,GAAsC;AACpD,EAAA,OAAO,CAAC,IAAA,EAAM,GAAA,EAAK,IAAA,KAAS;AAE1B,IAAA,GAAA,CAAI,EAAA,CAAG,UAAU,MAAM;AACrB,MAAA,KAAA,EAAM,CAAE,MAAM,MAAM;AAAA,MAEpB,CAAC,CAAA;AAAA,IACH,CAAC,CAAA;AAED,IAAA,IAAA,EAAK;AAAA,EACP,CAAA;AACF","file":"express.mjs","sourcesContent":["/**\n * Global Configuration\n *\n * Manages SDK configuration and transport instance.\n */\n\nimport type { LelemonConfig } from './types';\nimport { Transport } from './transport';\n\n// ─────────────────────────────────────────────────────────────\n// Global State\n// ─────────────────────────────────────────────────────────────\n\nlet globalConfig: LelemonConfig = {};\nlet globalTransport: Transport | null = null;\nlet initialized = false;\n\n// ─────────────────────────────────────────────────────────────\n// Configuration\n// ─────────────────────────────────────────────────────────────\n\nconst DEFAULT_ENDPOINT = 'https://api.lelemon.dev';\n\n/**\n * Initialize the SDK\n * Call once at app startup\n */\nexport function init(config: LelemonConfig = {}): void {\n  globalConfig = config;\n  globalTransport = createTransport(config);\n  initialized = true;\n}\n\n/**\n * Get current config\n */\nexport function getConfig(): LelemonConfig {\n  return globalConfig;\n}\n\n/**\n * Check if SDK is initialized\n */\nexport function isInitialized(): boolean {\n  return initialized;\n}\n\n/**\n * Check if SDK is enabled\n */\nexport function isEnabled(): boolean {\n  return getTransport().isEnabled();\n}\n\n// ─────────────────────────────────────────────────────────────\n// Transport\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Get or create transport instance\n */\nexport function getTransport(): Transport {\n  if (!globalTransport) {\n    globalTransport = createTransport(globalConfig);\n  }\n  return globalTransport;\n}\n\n/**\n * Flush all pending traces\n */\nexport async function flush(): Promise<void> {\n  if (globalTransport) {\n    await globalTransport.flush();\n  }\n}\n\n/**\n * Create transport instance\n */\nfunction createTransport(config: LelemonConfig): Transport {\n  const apiKey = config.apiKey ?? getEnvVar('LELEMON_API_KEY');\n\n  if (!apiKey && !config.disabled) {\n    console.warn(\n      '[Lelemon] No API key provided. Set apiKey in init() or LELEMON_API_KEY env var. Tracing disabled.'\n    );\n  }\n\n  return new Transport({\n    apiKey: apiKey ?? '',\n    endpoint: config.endpoint ?? DEFAULT_ENDPOINT,\n    debug: config.debug ?? false,\n    disabled: config.disabled ?? !apiKey,\n    batchSize: config.batchSize,\n    flushIntervalMs: config.flushIntervalMs,\n    requestTimeoutMs: config.requestTimeoutMs,\n  });\n}\n\n/**\n * Get environment variable (works in Node and edge)\n */\nfunction getEnvVar(name: string): string | undefined {\n  if (typeof process !== 'undefined' && process.env) {\n    return process.env[name];\n  }\n  return undefined;\n}\n","/**\n * Express Integration\n *\n * Middleware that automatically flushes traces when response finishes.\n *\n * @example\n * import express from 'express';\n * import { createMiddleware } from '@lelemondev/sdk/express';\n *\n * const app = express();\n * app.use(createMiddleware());\n */\n\nimport { flush } from '../core/config';\n\n// ─────────────────────────────────────────────────────────────\n// Types (minimal to avoid requiring express as dependency)\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Minimal Express request type (avoids requiring express as dependency)\n */\nexport interface ExpressRequest {\n  [key: string]: unknown;\n}\n\n/**\n * Minimal Express response type (avoids requiring express as dependency)\n */\nexport interface ExpressResponse {\n  on(event: 'finish' | 'close' | 'error', listener: () => void): this;\n  [key: string]: unknown;\n}\n\n/**\n * Express next function type\n */\nexport type ExpressNextFunction = (error?: unknown) => void;\n\n/**\n * Express middleware function type\n *\n * @param req - Express request object\n * @param res - Express response object\n * @param next - Next function to pass control\n */\nexport type ExpressMiddleware = (\n  req: ExpressRequest,\n  res: ExpressResponse,\n  next: ExpressNextFunction\n) => void;\n\n// ─────────────────────────────────────────────────────────────\n// Middleware\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Create Express middleware for automatic trace flushing\n *\n * Flushes traces when the response finishes (after res.send/res.json).\n * This is fire-and-forget and doesn't block the response.\n *\n * @returns Express middleware function\n *\n * @example\n * // Global middleware\n * app.use(createMiddleware());\n *\n * @example\n * // Per-route middleware\n * app.post('/chat', createMiddleware(), async (req, res) => {\n *   res.json({ ok: true });\n * });\n */\nexport function createMiddleware(): ExpressMiddleware {\n  return (_req, res, next) => {\n    // Flush when response is finished (after headers + body sent)\n    res.on('finish', () => {\n      flush().catch(() => {\n        // Silently ignore flush errors - fire and forget\n      });\n    });\n\n    next();\n  };\n}\n"]}