@lelemondev/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -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 };