observa-sdk 0.0.5 → 0.0.7

package/dist/index.d.cts

@@ -13,6 +13,11 @@ interface TrackEventInput {
     context?: string;
     model?: string;
     metadata?: Record<string, any>;
+    conversationId?: string;
+    sessionId?: string;
+    userId?: string;
+    messageIndex?: number;
+    parentMessageId?: string;
 }
 declare class Observa {
     private apiKey;
@@ -23,10 +28,137 @@ declare class Observa {
     private isProduction;
     private sampleRate;
     private maxResponseChars;
+    private eventBuffer;
+    private flushPromise;
+    private flushInProgress;
+    private maxBufferSize;
+    private flushIntervalMs;
+    private flushIntervalId;
+    private currentTraceId;
+    private rootSpanId;
+    private spanStack;
+    private traceStartTime;
     constructor(config: ObservaInitConfig);
-    track(event: TrackEventInput, action: () => Promise<Response>): Promise<Response>;
+    /**
+     * Flush buffered events to the API
+     * Returns a promise that resolves when all events are sent
+     */
+    flush(): Promise<void>;
+    /**
+     * Helper: Create base event properties
+     */
+    private createBaseEventProperties;
+    /**
+     * Helper: Add event to buffer with proper span hierarchy
+     */
+    private addEvent;
+    /**
+     * Start a new trace (manual trace management)
+     */
+    startTrace(options?: {
+        name?: string;
+        metadata?: Record<string, any>;
+        conversationId?: string;
+        sessionId?: string;
+        userId?: string;
+    }): string;
+    /**
+     * Track a tool call
+     */
+    trackToolCall(options: {
+        toolName: string;
+        args?: Record<string, any>;
+        result?: any;
+        resultStatus: "success" | "error" | "timeout";
+        latencyMs: number;
+        errorMessage?: string;
+    }): string;
+    /**
+     * Track a retrieval operation
+     */
+    trackRetrieval(options: {
+        contextIds?: string[];
+        contextHashes?: string[];
+        k?: number;
+        similarityScores?: number[];
+        latencyMs: number;
+    }): string;
+    /**
+     * Track an error with stack trace support
+     */
+    trackError(options: {
+        errorType: string;
+        errorMessage: string;
+        stackTrace?: string;
+        context?: Record<string, any>;
+        error?: Error;
+    }): string;
+    /**
+     * Track user feedback
+     */
+    trackFeedback(options: {
+        type: "like" | "dislike" | "rating" | "correction";
+        rating?: number;
+        comment?: string;
+        outcome?: "success" | "failure" | "partial";
+        conversationId?: string;
+        sessionId?: string;
+        userId?: string;
+        messageIndex?: number;
+        parentMessageId?: string;
+        agentName?: string;
+        version?: string;
+        route?: string;
+        parentSpanId?: string | null;
+        spanId?: string;
+    }): string;
+    /**
+     * Track final output
+     */
+    trackOutput(options: {
+        finalOutput?: string;
+        outputLength?: number;
+    }): string;
+    /**
+     * Execute a function within a span context (for nested operations)
+     * This allows tool calls to be nested under LLM calls, etc.
+     */
+    withSpan<T>(spanId: string, fn: () => T): T;
+    /**
+     * Execute an async function within a span context (for nested operations)
+     */
+    withSpanAsync<T>(spanId: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * End trace and send events (manual trace management)
+     */
+    endTrace(options?: {
+        outcome?: "success" | "error" | "timeout";
+    }): Promise<string>;
+    /**
+     * Convert legacy TraceData to canonical events
+     */
+    private traceDataToCanonicalEvents;
+    /**
+     * Internal flush implementation
+     */
+    private _doFlush;
+    /**
+     * Send canonical events with exponential backoff retry
+     */
+    private _sendEventsWithRetry;
+    /**
+     * Cleanup (call when shutting down)
+     */
+    end(): Promise<void>;
+    track(event: TrackEventInput, action: () => Promise<Response>, options?: {
+        trackBlocking?: boolean;
+    }): Promise<any>;
     private captureStream;
-    private sendTrace;
+    /**
+     * Send canonical events to Observa backend
+     * (internal method, use _sendEventsWithRetry for retry logic)
+     */
+    private sendEvents;
 }
 declare const init: (config: ObservaInitConfig) => Observa;
 

package/dist/index.d.ts

@@ -13,6 +13,11 @@ interface TrackEventInput {
     context?: string;
     model?: string;
     metadata?: Record<string, any>;
+    conversationId?: string;
+    sessionId?: string;
+    userId?: string;
+    messageIndex?: number;
+    parentMessageId?: string;
 }
 declare class Observa {
     private apiKey;
@@ -23,10 +28,137 @@ declare class Observa {
     private isProduction;
     private sampleRate;
     private maxResponseChars;
+    private eventBuffer;
+    private flushPromise;
+    private flushInProgress;
+    private maxBufferSize;
+    private flushIntervalMs;
+    private flushIntervalId;
+    private currentTraceId;
+    private rootSpanId;
+    private spanStack;
+    private traceStartTime;
     constructor(config: ObservaInitConfig);
-    track(event: TrackEventInput, action: () => Promise<Response>): Promise<Response>;
+    /**
+     * Flush buffered events to the API
+     * Returns a promise that resolves when all events are sent
+     */
+    flush(): Promise<void>;
+    /**
+     * Helper: Create base event properties
+     */
+    private createBaseEventProperties;
+    /**
+     * Helper: Add event to buffer with proper span hierarchy
+     */
+    private addEvent;
+    /**
+     * Start a new trace (manual trace management)
+     */
+    startTrace(options?: {
+        name?: string;
+        metadata?: Record<string, any>;
+        conversationId?: string;
+        sessionId?: string;
+        userId?: string;
+    }): string;
+    /**
+     * Track a tool call
+     */
+    trackToolCall(options: {
+        toolName: string;
+        args?: Record<string, any>;
+        result?: any;
+        resultStatus: "success" | "error" | "timeout";
+        latencyMs: number;
+        errorMessage?: string;
+    }): string;
+    /**
+     * Track a retrieval operation
+     */
+    trackRetrieval(options: {
+        contextIds?: string[];
+        contextHashes?: string[];
+        k?: number;
+        similarityScores?: number[];
+        latencyMs: number;
+    }): string;
+    /**
+     * Track an error with stack trace support
+     */
+    trackError(options: {
+        errorType: string;
+        errorMessage: string;
+        stackTrace?: string;
+        context?: Record<string, any>;
+        error?: Error;
+    }): string;
+    /**
+     * Track user feedback
+     */
+    trackFeedback(options: {
+        type: "like" | "dislike" | "rating" | "correction";
+        rating?: number;
+        comment?: string;
+        outcome?: "success" | "failure" | "partial";
+        conversationId?: string;
+        sessionId?: string;
+        userId?: string;
+        messageIndex?: number;
+        parentMessageId?: string;
+        agentName?: string;
+        version?: string;
+        route?: string;
+        parentSpanId?: string | null;
+        spanId?: string;
+    }): string;
+    /**
+     * Track final output
+     */
+    trackOutput(options: {
+        finalOutput?: string;
+        outputLength?: number;
+    }): string;
+    /**
+     * Execute a function within a span context (for nested operations)
+     * This allows tool calls to be nested under LLM calls, etc.
+     */
+    withSpan<T>(spanId: string, fn: () => T): T;
+    /**
+     * Execute an async function within a span context (for nested operations)
+     */
+    withSpanAsync<T>(spanId: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * End trace and send events (manual trace management)
+     */
+    endTrace(options?: {
+        outcome?: "success" | "error" | "timeout";
+    }): Promise<string>;
+    /**
+     * Convert legacy TraceData to canonical events
+     */
+    private traceDataToCanonicalEvents;
+    /**
+     * Internal flush implementation
+     */
+    private _doFlush;
+    /**
+     * Send canonical events with exponential backoff retry
+     */
+    private _sendEventsWithRetry;
+    /**
+     * Cleanup (call when shutting down)
+     */
+    end(): Promise<void>;
+    track(event: TrackEventInput, action: () => Promise<Response>, options?: {
+        trackBlocking?: boolean;
+    }): Promise<any>;
     private captureStream;
-    private sendTrace;
+    /**
+     * Send canonical events to Observa backend
+     * (internal method, use _sendEventsWithRetry for retry logic)
+     */
+    private sendEvents;
 }
 declare const init: (config: ObservaInitConfig) => Observa;