@lelemondev/sdk 0.1.0 → 0.2.1

package/README.md

@@ -1,151 +1,173 @@
-# @lelemon/sdk
-
-Low-friction LLM observability. **3 lines of code.**
-
-```typescript
-import { trace } from '@lelemon/sdk';
-
-const t = trace({ input: userMessage });
-try {
-  // ... your agent code ...
-  await t.success(messages);
-} catch (error) {
-  await t.error(error, messages);
-}
-```
-
-## Installation
-
-```bash
-npm install @lelemon/sdk
-# or
-yarn add @lelemon/sdk
-# or
-pnpm add @lelemon/sdk
-```
-
-## Setup
-
-Set your API key:
-
-```bash
-export LELEMON_API_KEY=le_your_api_key
-```
-
-Or configure programmatically:
-
-```typescript
-import { init } from '@lelemon/sdk';
-
-init({ apiKey: 'le_xxx' });
-```
-
-## Quick Start
-
-```typescript
-import { trace } from '@lelemon/sdk';
-
-async function runAgent(userMessage: string) {
-  const t = trace({ input: userMessage });
-
-  try {
-    const messages = [
-      { role: 'system', content: 'You are a helpful assistant.' },
-      { role: 'user', content: userMessage },
-    ];
-
-    const response = await openai.chat.completions.create({
-      model: 'gpt-4',
-      messages,
-    });
-
-    // Optional: log response to capture token usage
-    t.log(response);
-
-    messages.push(response.choices[0].message);
-
-    await t.success(messages);
-    return response.choices[0].message.content;
-  } catch (error) {
-    await t.error(error, messages);
-    throw error;
-  }
-}
-```
-
-## Supported Providers
-
-| Provider | Message Format | Auto-detected |
-|----------|---------------|---------------|
-| **OpenAI** | `role: 'user' \| 'assistant'` | Yes |
-| **Anthropic** | `role: 'user' \| 'assistant'` | Yes |
-| **Gemini** | `role: 'user' \| 'model'` | Yes |
-| **AWS Bedrock** | Anthropic format | Yes |
-
-## API Reference
-
-### `trace(options)`
-
-Start a new trace.
-
-```typescript
-const t = trace({
-  input: userMessage,        // Required
-  name: 'my-agent',          // Optional
-  sessionId: 'session-123',  // Optional
-  userId: 'user-456',        // Optional
-  metadata: { ... },         // Optional
-  tags: ['prod'],            // Optional
-});
-```
-
-### `t.success(messages)`
-
-Complete trace successfully.
-
-```typescript
-await t.success(messages);
-```
-
-### `t.error(error, messages?)`
-
-Complete trace with error.
-
-```typescript
-await t.error(error, messages);
-```
-
-### `t.log(response)`
-
-Log an LLM response to capture tokens (optional).
-
-```typescript
-t.log(response);
-```
-
-### `init(config)`
-
-Initialize SDK globally (optional).
-
-```typescript
-init({
-  apiKey: 'le_xxx',
-  endpoint: 'https://custom.endpoint.com',
-  debug: true,
-  disabled: process.env.NODE_ENV === 'test',
-});
-```
-
-## What Gets Captured
-
-- System prompt
-- User input
-- Tool calls and results
-- Final output
-- Token usage
-- Duration
-- Errors with stack traces
-
-## License
-
-MIT
+# @lelemondev/sdk
+
+[![npm version](https://img.shields.io/npm/v/@lelemondev/sdk.svg)](https://www.npmjs.com/package/@lelemondev/sdk)
+[![CI](https://github.com/lelemondev/lelemondev-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/lelemondev/lelemondev-sdk/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Fire-and-forget LLM observability for Node.js. Track your AI agents with 3 lines of code.
+
+## Features
+
+- 🔥 **Fire-and-forget** - Never blocks your code
+- 📦 **Auto-batching** - Efficient network usage
+- ⚡ **Zero config** - Works out of the box
+- 🛡️ **Error-safe** - Never crashes your app
+- 🌐 **Serverless-ready** - Built-in flush for Lambda/Vercel
+
+## Installation
+
+```bash
+npm install @lelemondev/sdk
+```
+
+## Quick Start
+
+```typescript
+import { init, trace, flush } from '@lelemondev/sdk';
+
+// Initialize once at app startup
+init({ apiKey: process.env.LELEMON_API_KEY });
+
+// Trace your agent (fire-and-forget, no awaits needed!)
+const t = trace({ input: userMessage });
+
+try {
+  const result = await myAgent(userMessage);
+  t.success(result.messages);  // Sync, doesn't block
+} catch (error) {
+  t.error(error);              // Sync, doesn't block
+  throw error;
+}
+
+// For serverless: flush before response
+await flush();
+```
+
+## API Reference
+
+### `init(config)`
+
+Initialize the SDK. Call once at app startup.
+
+```typescript
+init({
+  apiKey: 'le_xxx',           // Required (or set LELEMON_API_KEY env var)
+  endpoint: 'https://...',    // Optional, custom endpoint
+  debug: false,               // Optional, enable debug logs
+  batchSize: 10,              // Optional, items per batch
+  flushIntervalMs: 1000,      // Optional, auto-flush interval
+});
+```
+
+### `trace(options)`
+
+Start a new trace. Returns a `Trace` object.
+
+```typescript
+const t = trace({
+  input: userMessage,         // Required, the input to your agent
+  sessionId: 'session-123',   // Optional, group related traces
+  userId: 'user-456',         // Optional, identify the user
+  name: 'chat-agent',         // Optional, name for this trace
+  metadata: { ... },          // Optional, custom metadata
+  tags: ['prod', 'v2'],       // Optional, tags for filtering
+});
+```
+
+### `Trace.success(messages)`
+
+Complete the trace successfully. Fire-and-forget (no await needed).
+
+```typescript
+t.success(result.messages);
+```
+
+### `Trace.error(error, messages?)`
+
+Complete the trace with an error. Fire-and-forget (no await needed).
+
+```typescript
+t.error(error);
+t.error(error, partialMessages);  // Include messages up to failure
+```
+
+### `Trace.log(response)`
+
+Log an LLM response for token tracking (optional).
+
+```typescript
+const response = await openai.chat.completions.create(...);
+t.log(response);  // Extracts model, tokens automatically
+```
+
+### `flush()`
+
+Wait for all pending traces to be sent. Use in serverless environments.
+
+```typescript
+await flush();
+```
+
+## Serverless Usage
+
+### Vercel (Next.js)
+
+```typescript
+import { waitUntil } from '@vercel/functions';
+import { trace, flush } from '@lelemondev/sdk';
+
+export async function POST(req: Request) {
+  const t = trace({ input: message });
+
+  try {
+    const result = await myAgent(message);
+    t.success(result);
+    return Response.json(result);
+  } catch (error) {
+    t.error(error);
+    throw error;
+  } finally {
+    waitUntil(flush());  // Flush after response
+  }
+}
+```
+
+### AWS Lambda
+
+```typescript
+import { trace, flush } from '@lelemondev/sdk';
+
+export const handler = async (event) => {
+  const t = trace({ input: event.body });
+
+  try {
+    const result = await myAgent(event.body);
+    t.success(result);
+    return { statusCode: 200, body: JSON.stringify(result) };
+  } catch (error) {
+    t.error(error);
+    throw error;
+  } finally {
+    await flush();  // Always flush before Lambda ends
+  }
+};
+```
+
+## Supported Providers
+
+| Provider | Auto-detected |
+|----------|---------------|
+| OpenAI | ✅ |
+| Anthropic | ✅ |
+| Google Gemini | ✅ |
+| AWS Bedrock | ✅ |
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `LELEMON_API_KEY` | Your Lelemon API key (starts with `le_`) |
+
+## License
+
+MIT © [Lelemon](https://lelemon.dev)

package/dist/index.d.mts

@@ -20,6 +20,18 @@ interface LelemonConfig {
      * Disable tracing (useful for testing)
      */
     disabled?: boolean;
+    /**
+     * Number of items to batch before sending (default: 10)
+     */
+    batchSize?: number;
+    /**
+     * Interval in ms to flush pending items (default: 1000)
+     */
+    flushIntervalMs?: number;
+    /**
+     * Request timeout in ms (default: 10000)
+     */
+    requestTimeoutMs?: number;
 }
 interface TraceOptions {
     /**
@@ -125,7 +137,14 @@ interface CompleteTraceRequest {
 }
 
 /**
- * Transport layer for sending data to Lelemon API
+ * Transport layer with queue-based batching
+ *
+ * Features:
+ * - Fire-and-forget API (sync enqueue)
+ * - Automatic batching (by size or interval)
+ * - Single flush promise (no duplicate requests)
+ * - Graceful error handling (never crashes caller)
+ * - Request timeout protection
  */
 
 interface TransportConfig {
@@ -133,97 +152,146 @@ interface TransportConfig {
     endpoint: string;
     debug: boolean;
     disabled: boolean;
+    batchSize?: number;
+    flushIntervalMs?: number;
+    requestTimeoutMs?: number;
 }
 declare class Transport {
-    private config;
+    private readonly config;
+    private queue;
+    private flushPromise;
+    private flushTimer;
+    private pendingResolvers;
+    private idCounter;
     constructor(config: TransportConfig);
     /**
      * Check if transport is enabled
      */
     isEnabled(): boolean;
     /**
-     * Create a new trace
+     * Enqueue trace creation (returns promise that resolves to trace ID)
+     */
+    enqueueCreate(data: CreateTraceRequest): Promise<string | null>;
+    /**
+     * Enqueue trace completion (fire-and-forget)
      */
-    createTrace(data: CreateTraceRequest): Promise<{
-        id: string;
-    }>;
+    enqueueComplete(traceId: string, data: CompleteTraceRequest): void;
     /**
-     * Complete a trace (success or error)
+     * Flush all pending items
+     * Safe to call multiple times (deduplicates)
      */
-    completeTrace(traceId: string, data: CompleteTraceRequest): Promise<void>;
+    flush(): Promise<void>;
     /**
-     * Make HTTP request to API
+     * Get pending item count (for testing/debugging)
      */
+    getPendingCount(): number;
+    private generateTempId;
+    private enqueue;
+    private scheduleFlush;
+    private cancelScheduledFlush;
+    private sendBatch;
     private request;
+    private log;
 }
 
 /**
- * Lelemon Tracer - Simple, low-friction API
+ * Lelemon Tracer - Fire-and-forget LLM observability
  *
  * Usage:
  *   const t = trace({ input: userMessage });
  *   try {
- *     // your agent code
- *     t.success(messages);
+ *     const result = await myAgent(userMessage);
+ *     t.success(result.messages);
  *   } catch (error) {
- *     t.error(error, messages);
+ *     t.error(error);
+ *     throw error;
  *   }
+ *
+ * For serverless:
+ *   await flush(); // Before response
  */
 
 /**
- * Initialize the SDK globally (optional)
- * If not called, trace() will auto-initialize with env vars
+ * Initialize the SDK (optional, will auto-init with env vars)
+ *
+ * @example
+ * init({ apiKey: 'le_xxx' });
+ * init({ apiKey: 'le_xxx', debug: true });
  */
 declare function init(config?: LelemonConfig): void;
 /**
- * Active trace handle returned by trace()
+ * Start a new trace
+ *
+ * @example
+ * const t = trace({ input: userMessage });
+ * try {
+ *   const result = await myAgent(userMessage);
+ *   t.success(result.messages);
+ * } catch (error) {
+ *   t.error(error);
+ *   throw error;
+ * }
+ */
+declare function trace(options: TraceOptions): Trace;
+/**
+ * Flush all pending traces to the server
+ * Call this before process exit in serverless environments
+ *
+ * @example
+ * // In Next.js API route
+ * export async function POST(req: Request) {
+ *   // ... your code with traces ...
+ *   await flush();
+ *   return Response.json(result);
+ * }
+ *
+ * // With Vercel waitUntil
+ * import { waitUntil } from '@vercel/functions';
+ * waitUntil(flush());
  */
+declare function flush(): Promise<void>;
+/**
+ * Check if SDK is enabled
+ */
+declare function isEnabled(): boolean;
 declare class Trace {
     private id;
-    private transport;
-    private options;
-    private startTime;
+    private idPromise;
+    private readonly transport;
+    private readonly startTime;
+    private readonly debug;
+    private readonly disabled;
     private completed;
-    private debug;
-    private disabled;
     private llmCalls;
     constructor(options: TraceOptions, transport: Transport, debug: boolean, disabled: boolean);
     /**
-     * Initialize trace on server (called internally)
+     * Log an LLM response for token tracking
+     * Optional - use if you want per-call token counts
      */
-    init(): Promise<void>;
+    log(response: unknown): this;
     /**
-     * Log an LLM response (optional - for tracking individual calls)
-     * Use this if you want to track tokens per call, not just at the end
+     * Complete trace successfully (fire-and-forget)
+     *
+     * @param messages - Full message history (OpenAI/Anthropic format)
      */
-    log(response: unknown): void;
+    success(messages: unknown): void;
     /**
-     * Complete trace successfully
-     * @param messages - The full message history (OpenAI/Anthropic format)
+     * Complete trace with error (fire-and-forget)
+     *
+     * @param error - The error that occurred
+     * @param messages - Optional message history up to failure
      */
-    success(messages: unknown): Promise<void>;
+    error(error: Error | unknown, messages?: unknown): void;
     /**
-     * Complete trace with error
-     * @param error - The error that occurred
-     * @param messages - The message history up to the failure (optional)
+     * Get the trace ID (may be null if not yet created or failed)
+     */
+    getId(): string | null;
+    /**
+     * Wait for trace ID to be available
      */
-    error(error: Error | unknown, messages?: unknown): Promise<void>;
+    waitForId(): Promise<string | null>;
+    private aggregateCalls;
 }
-/**
- * Start a new trace
- *
- * @example
- * const t = trace({ input: userMessage });
- * try {
- *   const messages = [...];
- *   // ... your agent code ...
- *   await t.success(messages);
- * } catch (error) {
- *   await t.error(error, messages);
- *   throw error;
- * }
- */
-declare function trace(options: TraceOptions): Trace;
 
 /**
  * Message Parser
@@ -245,4 +313,4 @@ declare function parseResponse(response: unknown): Partial<ParsedLLMCall>;
  */
 declare function parseBedrockResponse(body: unknown): Partial<ParsedLLMCall>;
 
-export { type AnthropicMessage, type LelemonConfig, type Message, type OpenAIMessage, type ParsedLLMCall, type ParsedToolCall, type ParsedTrace, Trace, type TraceOptions, init, parseBedrockResponse, parseMessages, parseResponse, trace };
+export { type AnthropicMessage, type LelemonConfig, type Message, type OpenAIMessage, type ParsedLLMCall, type ParsedToolCall, type ParsedTrace, Trace, type TraceOptions, flush, init, isEnabled, parseBedrockResponse, parseMessages, parseResponse, trace };