@lelemondev/sdk 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,316 +1,88 @@
 /**
- * Lelemon SDK Types
- * Minimal, low-friction API for LLM observability
+ * Core types for Lelemon SDK
  */
 interface LelemonConfig {
-    /**
-     * API key for authentication (starts with 'le_')
-     * Can also be set via LELEMON_API_KEY env var
-     */
+    /** API key (or set LELEMON_API_KEY env var) */
     apiKey?: string;
-    /**
-     * API endpoint (default: https://api.lelemon.dev)
-     */
+    /** API endpoint (default: https://api.lelemon.dev) */
     endpoint?: string;
-    /**
-     * Enable debug logging
-     */
+    /** Enable debug logging */
     debug?: boolean;
-    /**
-     * Disable tracing (useful for testing)
-     */
+    /** Disable tracing */
     disabled?: boolean;
-    /**
-     * Number of items to batch before sending (default: 10)
-     */
+    /** Batch size before flush (default: 10) */
     batchSize?: number;
-    /**
-     * Interval in ms to flush pending items (default: 1000)
-     */
+    /** Auto-flush interval in ms (default: 1000) */
     flushIntervalMs?: number;
-    /**
-     * Request timeout in ms (default: 10000)
-     */
+    /** Request timeout in ms (default: 10000) */
     requestTimeoutMs?: number;
 }
-interface TraceOptions {
-    /**
-     * Initial input (user message, prompt, etc.)
-     */
-    input: unknown;
-    /**
-     * Session ID to group related traces
-     */
+type ProviderName = 'openai' | 'anthropic' | 'google' | 'bedrock' | 'unknown';
+interface ObserveOptions {
+    /** Session ID to group related calls */
     sessionId?: string;
-    /**
-     * User ID for the end user
-     */
+    /** User ID for the end user */
     userId?: string;
-    /**
-     * Custom metadata
-     */
+    /** Custom metadata added to all traces */
     metadata?: Record<string, unknown>;
-    /**
-     * Tags for filtering
-     */
+    /** Tags for filtering */
     tags?: string[];
-    /**
-     * Name for this trace (e.g., 'chat-agent', 'summarizer')
-     */
-    name?: string;
-}
-interface OpenAIMessage {
-    role: 'system' | 'user' | 'assistant' | 'tool';
-    content: string | null;
-    tool_calls?: OpenAIToolCall[];
-    tool_call_id?: string;
-}
-interface OpenAIToolCall {
-    id: string;
-    type: 'function';
-    function: {
-        name: string;
-        arguments: string;
-    };
-}
-interface AnthropicMessage {
-    role: 'user' | 'assistant';
-    content: string | AnthropicContent[];
-}
-interface AnthropicContent {
-    type: 'text' | 'tool_use' | 'tool_result';
-    text?: string;
-    id?: string;
-    name?: string;
-    input?: unknown;
-    tool_use_id?: string;
-    content?: string;
-}
-type Message = OpenAIMessage | AnthropicMessage | Record<string, unknown>;
-interface ParsedTrace {
-    systemPrompt?: string;
-    userInput?: string;
-    output?: string;
-    llmCalls: ParsedLLMCall[];
-    toolCalls: ParsedToolCall[];
-    totalInputTokens: number;
-    totalOutputTokens: number;
-    models: string[];
-    provider?: 'openai' | 'anthropic' | 'gemini' | 'bedrock' | 'unknown';
-}
-interface ParsedLLMCall {
-    model?: string;
-    provider?: string;
-    inputTokens?: number;
-    outputTokens?: number;
-    input?: unknown;
-    output?: unknown;
-    toolCalls?: ParsedToolCall[];
-}
-interface ParsedToolCall {
-    name: string;
-    input: unknown;
-    output?: unknown;
-}
-interface CreateTraceRequest {
-    name?: string;
-    sessionId?: string;
-    userId?: string;
-    input?: unknown;
-    metadata?: Record<string, unknown>;
-    tags?: string[];
-}
-interface CompleteTraceRequest {
-    status: 'completed' | 'error';
-    output?: unknown;
-    errorMessage?: string;
-    errorStack?: string;
-    systemPrompt?: string;
-    llmCalls?: ParsedLLMCall[];
-    toolCalls?: ParsedToolCall[];
-    models?: string[];
-    totalInputTokens?: number;
-    totalOutputTokens?: number;
-    totalCostUsd?: number;
-    durationMs?: number;
-    metadata?: Record<string, unknown>;
-}
-
-/**
- * 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 {
-    apiKey: string;
-    endpoint: string;
-    debug: boolean;
-    disabled: boolean;
-    batchSize?: number;
-    flushIntervalMs?: number;
-    requestTimeoutMs?: number;
-}
-declare class Transport {
-    private readonly config;
-    private queue;
-    private flushPromise;
-    private flushTimer;
-    private pendingResolvers;
-    private idCounter;
-    constructor(config: TransportConfig);
-    /**
-     * Check if transport is enabled
-     */
-    isEnabled(): boolean;
-    /**
-     * Enqueue trace creation (returns promise that resolves to trace ID)
-     */
-    enqueueCreate(data: CreateTraceRequest): Promise<string | null>;
-    /**
-     * Enqueue trace completion (fire-and-forget)
-     */
-    enqueueComplete(traceId: string, data: CompleteTraceRequest): void;
-    /**
-     * Flush all pending items
-     * Safe to call multiple times (deduplicates)
-     */
-    flush(): Promise<void>;
-    /**
-     * 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 - Fire-and-forget LLM observability
- *
- * Usage:
- *   const t = trace({ input: userMessage });
- *   try {
- *     const result = await myAgent(userMessage);
- *     t.success(result.messages);
- *   } catch (error) {
- *     t.error(error);
- *     throw error;
- *   }
+ * Global Configuration
  *
- * For serverless:
- *   await flush(); // Before response
+ * Manages SDK configuration and transport instance.
  */
 
 /**
- * Initialize the SDK (optional, will auto-init with env vars)
- *
- * @example
- * init({ apiKey: 'le_xxx' });
- * init({ apiKey: 'le_xxx', debug: true });
+ * Initialize the SDK
+ * Call once at app startup
  */
 declare function init(config?: LelemonConfig): void;
-/**
- * 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 idPromise;
-    private readonly transport;
-    private readonly startTime;
-    private readonly debug;
-    private readonly disabled;
-    private completed;
-    private llmCalls;
-    constructor(options: TraceOptions, transport: Transport, debug: boolean, disabled: boolean);
-    /**
-     * Log an LLM response for token tracking
-     * Optional - use if you want per-call token counts
-     */
-    log(response: unknown): this;
-    /**
-     * Complete trace successfully (fire-and-forget)
-     *
-     * @param messages - Full message history (OpenAI/Anthropic format)
-     */
-    success(messages: unknown): void;
-    /**
-     * Complete trace with error (fire-and-forget)
-     *
-     * @param error - The error that occurred
-     * @param messages - Optional message history up to failure
-     */
-    error(error: Error | unknown, messages?: unknown): void;
-    /**
-     * Get the trace ID (may be null if not yet created or failed)
-     */
-    getId(): string | null;
-    /**
-     * Wait for trace ID to be available
-     */
-    waitForId(): Promise<string | null>;
-    private aggregateCalls;
-}
-
 /**
- * Message Parser
- * Auto-detects OpenAI/Anthropic/Gemini message formats and extracts relevant data
+ * Flush all pending traces
  */
+declare function flush(): Promise<void>;
 
 /**
- * Parse messages array and extract structured data
+ * Observe Function
+ *
+ * Main entry point for wrapping LLM clients with automatic tracing.
  */
-declare function parseMessages(messages: unknown): ParsedTrace;
+
 /**
- * Extract data from an OpenAI/Anthropic/Bedrock response object
- * This handles the raw API response (not the messages array)
+ * Wrap an LLM client with automatic tracing
+ *
+ * @param client - OpenAI or Anthropic client instance
+ * @param options - Optional context (sessionId, userId, etc.)
+ * @returns The wrapped client with the same type
+ *
+ * @example
+ * import { observe } from '@lelemondev/sdk';
+ * import OpenAI from 'openai';
+ *
+ * const openai = observe(new OpenAI());
+ *
+ * // All calls are now automatically traced
+ * const response = await openai.chat.completions.create({...});
  */
-declare function parseResponse(response: unknown): Partial<ParsedLLMCall>;
+declare function observe<T>(client: T, options?: ObserveOptions): T;
 /**
- * Parse Bedrock InvokeModel response body
- * Call this with the parsed JSON body from Bedrock
+ * Create a scoped observe function with preset context
+ *
+ * @example
+ * const observeWithSession = createObserve({
+ *   sessionId: 'session-123',
+ *   userId: 'user-456',
+ * });
+ *
+ * const openai = observeWithSession(new OpenAI());
  */
-declare function parseBedrockResponse(body: unknown): Partial<ParsedLLMCall>;
+declare function createObserve(defaultOptions: ObserveOptions): <T>(client: T, options?: ObserveOptions) => T;
 
-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 };
+export { type LelemonConfig, type ObserveOptions, type ProviderName, createObserve, flush, init, isEnabled, observe };