@lelemondev/sdk 0.2.1 → 0.4.0

package/dist/hono.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/config.ts","../src/integrations/hono.ts"],"names":[],"mappings":";;;;AAuEA,eAAsB,KAAA,GAAuB;AAI7C;;;ACPO,SAAS,gBAAA,GAAmC;AACjD,EAAA,OAAO,OAAO,GAAG,IAAA,KAAS;AACxB,IAAA,MAAM,IAAA,EAAK;AAGX,IAAA,IAAI,CAAA,CAAE,cAAc,SAAA,EAAW;AAC7B,MAAA,CAAA,CAAE,YAAA,CAAa,SAAA,CAAU,KAAA,EAAO,CAAA;AAAA,IAClC,CAAA,MAAO;AAEL,MAAA,KAAA,EAAM,CAAE,MAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IACxB;AAAA,EACF,CAAA;AACF","file":"hono.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 * Hono Integration\n *\n * Middleware for Hono framework (Cloudflare Workers, Deno, Bun, Node.js).\n * Uses executionCtx.waitUntil() when available for non-blocking flush.\n *\n * @example\n * import { Hono } from 'hono';\n * import { createMiddleware } from '@lelemondev/sdk/hono';\n *\n * const app = new Hono();\n * app.use(createMiddleware());\n */\n\nimport { flush } from '../core/config';\n\n// ─────────────────────────────────────────────────────────────\n// Types (minimal to avoid requiring hono as dependency)\n// ─────────────────────────────────────────────────────────────\n\ninterface ExecutionContext {\n  waitUntil(promise: Promise<unknown>): void;\n  passThroughOnException(): void;\n}\n\ninterface HonoContext {\n  req: {\n    raw: Request;\n    [key: string]: unknown;\n  };\n  res: Response | undefined;\n  executionCtx?: ExecutionContext;\n  [key: string]: unknown;\n}\n\ntype NextFunction = () => Promise<void>;\n\ntype HonoMiddleware = (c: HonoContext, next: NextFunction) => Promise<void>;\n\n// ─────────────────────────────────────────────────────────────\n// Middleware\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Create Hono middleware for automatic trace flushing\n *\n * On Cloudflare Workers/Deno Deploy: uses executionCtx.waitUntil() for non-blocking flush\n * On Node.js/Bun: flushes after response (fire-and-forget)\n *\n * @returns Hono middleware function\n *\n * @example\n * import { Hono } from 'hono';\n * import { createMiddleware } from '@lelemondev/sdk/hono';\n *\n * const app = new Hono();\n *\n * // Global middleware\n * app.use(createMiddleware());\n *\n * app.post('/chat', async (c) => {\n *   const openai = observe(new OpenAI());\n *   const result = await openai.chat.completions.create({...});\n *   return c.json(result);\n * });\n *\n * export default app;\n */\nexport function createMiddleware(): HonoMiddleware {\n  return async (c, next) => {\n    await next();\n\n    // Use waitUntil if available (Cloudflare Workers, Deno Deploy)\n    if (c.executionCtx?.waitUntil) {\n      c.executionCtx.waitUntil(flush());\n    } else {\n      // Fire-and-forget for Node.js/Bun\n      flush().catch(() => {});\n    }\n  };\n}\n"]}

package/dist/hono.mjs

@@ -0,0 +1,21 @@
+/* @lelemondev/sdk - LLM Observability */
+
+async function flush() {
+}
+
+// src/integrations/hono.ts
+function createMiddleware() {
+  return async (c, next) => {
+    await next();
+    if (c.executionCtx?.waitUntil) {
+      c.executionCtx.waitUntil(flush());
+    } else {
+      flush().catch(() => {
+      });
+    }
+  };
+}
+
+export { createMiddleware };
+//# sourceMappingURL=hono.mjs.map
+//# sourceMappingURL=hono.mjs.map

package/dist/hono.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/config.ts","../src/integrations/hono.ts"],"names":[],"mappings":";;AAuEA,eAAsB,KAAA,GAAuB;AAI7C;;;ACPO,SAAS,gBAAA,GAAmC;AACjD,EAAA,OAAO,OAAO,GAAG,IAAA,KAAS;AACxB,IAAA,MAAM,IAAA,EAAK;AAGX,IAAA,IAAI,CAAA,CAAE,cAAc,SAAA,EAAW;AAC7B,MAAA,CAAA,CAAE,YAAA,CAAa,SAAA,CAAU,KAAA,EAAO,CAAA;AAAA,IAClC,CAAA,MAAO;AAEL,MAAA,KAAA,EAAM,CAAE,MAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IACxB;AAAA,EACF,CAAA;AACF","file":"hono.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 * Hono Integration\n *\n * Middleware for Hono framework (Cloudflare Workers, Deno, Bun, Node.js).\n * Uses executionCtx.waitUntil() when available for non-blocking flush.\n *\n * @example\n * import { Hono } from 'hono';\n * import { createMiddleware } from '@lelemondev/sdk/hono';\n *\n * const app = new Hono();\n * app.use(createMiddleware());\n */\n\nimport { flush } from '../core/config';\n\n// ─────────────────────────────────────────────────────────────\n// Types (minimal to avoid requiring hono as dependency)\n// ─────────────────────────────────────────────────────────────\n\ninterface ExecutionContext {\n  waitUntil(promise: Promise<unknown>): void;\n  passThroughOnException(): void;\n}\n\ninterface HonoContext {\n  req: {\n    raw: Request;\n    [key: string]: unknown;\n  };\n  res: Response | undefined;\n  executionCtx?: ExecutionContext;\n  [key: string]: unknown;\n}\n\ntype NextFunction = () => Promise<void>;\n\ntype HonoMiddleware = (c: HonoContext, next: NextFunction) => Promise<void>;\n\n// ─────────────────────────────────────────────────────────────\n// Middleware\n// ─────────────────────────────────────────────────────────────\n\n/**\n * Create Hono middleware for automatic trace flushing\n *\n * On Cloudflare Workers/Deno Deploy: uses executionCtx.waitUntil() for non-blocking flush\n * On Node.js/Bun: flushes after response (fire-and-forget)\n *\n * @returns Hono middleware function\n *\n * @example\n * import { Hono } from 'hono';\n * import { createMiddleware } from '@lelemondev/sdk/hono';\n *\n * const app = new Hono();\n *\n * // Global middleware\n * app.use(createMiddleware());\n *\n * app.post('/chat', async (c) => {\n *   const openai = observe(new OpenAI());\n *   const result = await openai.chat.completions.create({...});\n *   return c.json(result);\n * });\n *\n * export default app;\n */\nexport function createMiddleware(): HonoMiddleware {\n  return async (c, next) => {\n    await next();\n\n    // Use waitUntil if available (Cloudflare Workers, Deno Deploy)\n    if (c.executionCtx?.waitUntil) {\n      c.executionCtx.waitUntil(flush());\n    } else {\n      // Fire-and-forget for Node.js/Bun\n      flush().catch(() => {});\n    }\n  };\n}\n"]}

package/dist/index.d.mts

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