@compass-ai/nova 1.0.72 → 1.0.74

package/dist/services/token-tracker.d.ts

@@ -0,0 +1,290 @@
+/**
+ * Token usage tracking service for recording API call metrics, calculating costs,
+ * aggregating session totals, and exporting usage data.
+ *
+ * This module provides comprehensive token tracking functionality for the Compass CLI,
+ * enabling users to monitor their API usage, estimate costs, and receive warnings
+ * when approaching usage thresholds.
+ */
+import { TokenUsage, SessionTokenUsage, TokenMetrics, TokenWarning } from '../types/token.js';
+import type { PlanStatus, PlanType, UnifiedLimitCheckResult } from '../types/index.js';
+import { TokenLimitStore } from './token-limit-store.js';
+/**
+ * Structure for persisted token usage data
+ */
+interface TokenUsageData {
+    /** Version of the data format */
+    version: string;
+    /** Array of all tracked sessions */
+    sessions: SessionTokenUsage[];
+    /** ID of the currently active session */
+    currentSessionId: string | null;
+    /** Last updated timestamp */
+    lastUpdated: string;
+}
+/**
+ * TokenTracker class provides comprehensive token usage tracking for API calls.
+ *
+ * Features:
+ * - Session-based tracking with automatic aggregation
+ * - Cost estimation based on model pricing
+ * - Warning system for usage thresholds
+ * - Persistent storage with automatic save/load
+ * - Detailed metrics and statistics
+ * - Export functionality for usage data
+ */
+declare class TokenTracker {
+    private data;
+    private currentSession;
+    private warningThreshold;
+    private costWarningThreshold;
+    private initialized;
+    private dirty;
+    private tokenWarningEmitted;
+    private costWarningEmitted;
+    constructor();
+    /**
+     * Initializes the token tracker by loading persisted data.
+     * Must be called before using other methods.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Starts a new tracking session.
+     * If a session ID is provided, it will be used; otherwise, a new UUID is generated.
+     *
+     * @param sessionId - Optional session ID to use
+     * @returns The session ID of the new session
+     */
+    startSession(sessionId?: string): string;
+    /**
+     * Records token usage for an API call.
+     * Automatically starts a session if none is active.
+     *
+     * @param model - The model ID used for the API call
+     * @param usage - Token usage statistics from the API response
+     * @param purpose - Optional description of the API call purpose
+     */
+    recordUsage(model: string, usage: TokenUsage, purpose?: string): Promise<void>;
+    /**
+     * Gets the current session's token usage.
+     *
+     * @returns The current session usage or null if no session is active
+     */
+    getCurrentSessionUsage(): SessionTokenUsage | null;
+    /**
+     * Gets usage metrics for the current session.
+     *
+     * @returns Token metrics for the current session or null if no session/calls
+     */
+    getSessionMetrics(): TokenMetrics | null;
+    /**
+     * Gets all-time usage statistics across all sessions.
+     *
+     * @returns Aggregated token metrics across all sessions
+     */
+    getAllTimeStats(): TokenMetrics;
+    /**
+     * Gets usage statistics for a specific time period.
+     *
+     * @param startDate - Start of the period
+     * @param endDate - End of the period (defaults to now)
+     * @returns Token metrics for the specified period
+     */
+    getStatsByPeriod(startDate: Date, endDate?: Date): TokenMetrics;
+    /**
+     * Gets usage statistics grouped by model.
+     *
+     * @returns Map of model ID to token metrics
+     */
+    getStatsByModel(): Map<string, TokenMetrics>;
+    /**
+     * Ends the current session and marks it as complete.
+     */
+    endSession(): Promise<void>;
+    /**
+     * Exports all usage data for backup or analysis.
+     *
+     * @returns Complete token usage data structure
+     */
+    exportUsage(): Promise<TokenUsageData>;
+    /**
+     * Exports usage data for a specific session.
+     *
+     * @param sessionId - The session ID to export
+     * @returns Session usage data or null if not found
+     */
+    getSessionById(sessionId: string): SessionTokenUsage | null;
+    /**
+     * Gets all sessions, optionally filtered by date range.
+     *
+     * @param startDate - Optional start date filter
+     * @param endDate - Optional end date filter
+     * @returns Array of session usage data
+     */
+    getSessions(startDate?: Date, endDate?: Date): SessionTokenUsage[];
+    /**
+     * Sets the warning threshold for token usage.
+     *
+     * @param tokens - Token count threshold for warnings
+     */
+    setWarningThreshold(tokens: number): void;
+    /**
+     * Gets the current warning threshold.
+     *
+     * @returns The current token warning threshold
+     */
+    getWarningThreshold(): number;
+    /**
+     * Sets the cost warning threshold.
+     *
+     * @param cost - Cost threshold in USD for warnings
+     */
+    setCostWarningThreshold(cost: number): void;
+    /**
+     * Gets the current cost warning threshold.
+     *
+     * @returns The current cost warning threshold in USD
+     */
+    getCostWarningThreshold(): number;
+    /**
+     * Checks for any warning conditions and returns applicable warnings.
+     *
+     * @returns Array of token warnings
+     */
+    checkWarnings(): TokenWarning[];
+    /** Lazily-initialized reference to the unified token limit store. */
+    private _limitStore;
+    /**
+     * Sets the TokenLimitStore instance used for rolling window tracking.
+     * Must be called before using any limit-related methods.
+     */
+    setLimitStore(store: TokenLimitStore): void;
+    /** Returns the limit store, throwing if not yet wired up. */
+    private getLimitStore;
+    /**
+     * Resolves the applicable token limits for a model under a given plan.
+     *
+     * @param modelId - The model ID to resolve limits for
+     * @param planStatus - The user's current plan status
+     * @param planType - The subscription tier (only used when planStatus === 'active')
+     * @returns General and model-specific limits
+     */
+    resolveLimit(modelId: string, planStatus: PlanStatus, planType?: PlanType | null): {
+        generalLimit: number;
+        modelLimit: number;
+    };
+    /**
+     * Checks whether an API call for a given model is allowed under the
+     * token limits for the current 6-hour window.
+     *
+     * Loads the state (which resets if the window expired), reads flat
+     * counters, and compares against both the general (aggregate) limit
+     * and the per-model limit.
+     *
+     * @param modelId - The model ID to check
+     * @param planStatus - The user's current plan status
+     * @param planType - The subscription tier (only used when planStatus === 'active')
+     * @returns Check result with allowed status and remaining tokens
+     */
+    checkLimit(modelId: string, planStatus: PlanStatus, planType?: PlanType | null): Promise<UnifiedLimitCheckResult>;
+    /**
+     * Records token usage against the rolling window limit store.
+     * This is separate from the session analytics `recordUsage` method.
+     *
+     * @param modelId - The model that consumed tokens
+     * @param tokens - Number of tokens consumed
+     */
+    recordLimitUsage(modelId: string, tokens: number): Promise<void>;
+    /**
+     * Gets the total tokens used for a specific model within the rolling window.
+     *
+     * @param modelId - The model to check
+     * @returns Number of tokens used in the current window
+     */
+    getUsageForModel(modelId: string): Promise<number>;
+    /**
+     * Gets the remaining tokens for a model under the current plan.
+     *
+     * @param modelId - The model to check
+     * @param planStatus - The user's current plan status
+     * @param planType - The subscription tier (only used when planStatus === 'active')
+     * @returns Remaining tokens for the model
+     */
+    getRemainingTokens(modelId: string, planStatus: PlanStatus, planType?: PlanType | null): Promise<number>;
+    /**
+     * Clears all usage data. Use with caution.
+     */
+    clearAllData(): Promise<void>;
+    /**
+     * Clears usage data older than the specified number of days.
+     *
+     * @param days - Number of days to retain
+     * @returns Number of sessions removed
+     */
+    clearOldData(days: number): Promise<number>;
+    /**
+     * Calculates cost for token usage based on model pricing.
+     *
+     * @param usage - Token usage statistics
+     * @param model - Model ID for pricing lookup
+     * @returns Cost estimate breakdown
+     */
+    private calculateCost;
+    /**
+     * Updates the current session's totals based on all calls.
+     */
+    private updateSessionTotals;
+    /**
+     * Calculates the average of an array of numbers.
+     *
+     * @param numbers - Array of numbers to average
+     * @returns The average, rounded to nearest integer
+     */
+    private calculateAverage;
+    /**
+     * Creates an empty token usage object.
+     *
+     * @returns Empty TokenUsage object
+     */
+    private createEmptyTokenUsage;
+    /**
+     * Creates an empty cost estimate object.
+     *
+     * @returns Empty CostEstimate object
+     */
+    private createEmptyCostEstimate;
+    /**
+     * Gets the file path for token usage data storage.
+     *
+     * @returns Full path to the token usage file
+     */
+    private getFilePath;
+    /**
+     * Loads token usage data from disk.
+     */
+    private load;
+    /**
+     * Saves token usage data to disk.
+     */
+    private save;
+    /**
+     * Forces a save of the current data, regardless of dirty state.
+     */
+    forceSave(): Promise<void>;
+}
+/**
+ * Gets the singleton TokenTracker instance.
+ * Creates and initializes the instance on first call.
+ *
+ * @returns Promise resolving to the TokenTracker instance
+ */
+export declare function getTokenTracker(): Promise<TokenTracker>;
+/**
+ * Creates a new TokenTracker instance with custom configuration.
+ * Use this when you need a separate instance from the singleton.
+ *
+ * @returns A new TokenTracker instance (not initialized)
+ */
+export declare function createTokenTracker(): TokenTracker;
+export { TokenTracker };
+//# sourceMappingURL=token-tracker.d.ts.map

package/dist/services/token-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-tracker.d.ts","sourceRoot":"","sources":["../../src/services/token-tracker.ts"],"names":[],"mappings":"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"}