/**
 * Usage Tracking Types
 *
 * Types for tracking token usage across LLM calls.
 * Note: We track tokens only, not dollar costs (pricing changes frequently
 * and providing inaccurate cost info would be misleading).
 */
/**
 * Token usage for a single LLM call
 */
export interface TokenUsage {
    /** Input/prompt tokens */
    inputTokens: number;
    /** Output/completion tokens */
    outputTokens: number;
    /** Total tokens (input + output) */
    totalTokens: number;
    /** Cache read tokens (if applicable) */
    cacheReadTokens?: number;
    /** Cache creation tokens (if applicable) */
    cacheCreationTokens?: number;
}
/**
 * A single usage record
 */
export interface UsageRecord {
    /** Unique ID for this record */
    id: string;
    /** Timestamp of the call */
    timestamp: Date;
    /** Model used */
    model: string;
    /** Provider name */
    provider: string;
    /** Token usage */
    tokens: TokenUsage;
    /** Session ID (if tracking by session) */
    sessionId?: string;
    /** Additional metadata */
    metadata?: Record<string, unknown>;
}
/**
 * Aggregated usage statistics
 */
export interface UsageStats {
    /** Total number of LLM calls */
    totalCalls: number;
    /** Total input tokens */
    totalInputTokens: number;
    /** Total output tokens */
    totalOutputTokens: number;
    /** Total tokens */
    totalTokens: number;
    /** Total cache read tokens */
    totalCacheReadTokens: number;
    /** Total cache creation tokens */
    totalCacheCreationTokens: number;
    /** Average tokens per call */
    averageTokensPerCall: number;
    /** First call timestamp */
    firstCall?: Date;
    /** Last call timestamp */
    lastCall?: Date;
    /** Usage by model */
    byModel: Record<string, {
        calls: number;
        inputTokens: number;
        outputTokens: number;
        totalTokens: number;
    }>;
}
/**
 * Token budget configuration
 */
export interface TokenBudgetConfig {
    /** Maximum total tokens allowed */
    maxTotalTokens?: number;
    /** Maximum input tokens allowed */
    maxInputTokens?: number;
    /** Maximum output tokens allowed */
    maxOutputTokens?: number;
    /** Maximum tokens per session */
    maxTokensPerSession?: number;
    /** Warning threshold (0-1, triggers warning event when utilization reaches this) */
    warningThreshold?: number;
}
/**
 * Budget status
 */
export interface BudgetStatus {
    /** Current total tokens */
    currentTokens: number;
    /** Current input tokens */
    currentInputTokens: number;
    /** Current output tokens */
    currentOutputTokens: number;
    /** Token limit (if set) */
    tokenLimit?: number;
    /** Token utilization (0-1) */
    tokenUtilization?: number;
    /** Whether budget is exceeded */
    exceeded: boolean;
    /** Whether warning threshold is reached */
    warning: boolean;
}
/**
 * Usage tracker event types
 */
export type UsageEventType = 'usage:recorded' | 'usage:budget_warning' | 'usage:budget_exceeded' | 'usage:reset';
/**
 * Usage tracker events
 */
export type UsageEvent = {
    type: 'usage:recorded';
    record: UsageRecord;
    stats: UsageStats;
} | {
    type: 'usage:budget_warning';
    status: BudgetStatus;
    threshold: number;
} | {
    type: 'usage:budget_exceeded';
    status: BudgetStatus;
} | {
    type: 'usage:reset';
    previousStats: UsageStats;
};
/**
 * Event handler for usage events
 */
export type UsageEventHandler = (event: UsageEvent) => void;
/**
 * Options for UsageTracker
 */
export interface UsageTrackerOptions {
    /** Whether tracking is enabled (default: true) */
    enabled?: boolean;
    /** Token budget configuration */
    budget?: TokenBudgetConfig;
    /** Session ID for grouping */
    sessionId?: string;
}
/**
 * Input for recording usage
 */
export interface RecordUsageInput {
    /** Model used */
    model: string;
    /** Provider name */
    provider: string;
    /** Token usage */
    tokens: TokenUsage;
    /** Session ID override */
    sessionId?: string;
    /** Additional metadata */
    metadata?: Record<string, unknown>;
}