feat (v1.0.0): initial refactor and redesign
This commit is contained in:
parent
3058aa1ab4
commit
fe9b50b30e
134 changed files with 17792 additions and 3670 deletions
362
lib/types/ai.ts
Normal file
362
lib/types/ai.ts
Normal file
|
|
@ -0,0 +1,362 @@
|
|||
/**
|
||||
* Type definitions for AI usage analytics and token tracking.
|
||||
*
|
||||
* @remarks
|
||||
* This module contains interfaces for Claude AI usage data, including:
|
||||
* - Token consumption metrics (input, output, cache)
|
||||
* - Cost calculations
|
||||
* - Daily aggregations
|
||||
* - Trend analysis
|
||||
* - Model-specific breakdowns
|
||||
*
|
||||
* @module lib/types/ai
|
||||
* @category Types
|
||||
*/
|
||||
|
||||
/**
|
||||
* Breakdown of AI usage metrics for a specific model.
|
||||
*
|
||||
* @remarks
|
||||
* Contains token counts and cost for a single AI model within a time period.
|
||||
* Used to track usage across different models (e.g., Claude Sonnet, Opus).
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const breakdown: ModelBreakdown = {
|
||||
* modelName: 'claude-sonnet-4-20250514',
|
||||
* inputTokens: 150000,
|
||||
* outputTokens: 75000,
|
||||
* cacheCreationTokens: 5000,
|
||||
* cacheReadTokens: 50000,
|
||||
* cost: 2.45
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface ModelBreakdown {
|
||||
/** Model identifier (e.g., 'claude-sonnet-4-20250514') */
|
||||
modelName: string
|
||||
/** Number of input tokens consumed */
|
||||
inputTokens: number
|
||||
/** Number of output tokens generated */
|
||||
outputTokens: number
|
||||
/** Number of tokens written to cache */
|
||||
cacheCreationTokens: number
|
||||
/** Number of tokens read from cache */
|
||||
cacheReadTokens: number
|
||||
/** Total cost in USD for this model's usage */
|
||||
cost: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Aggregated AI usage data for a single day.
|
||||
*
|
||||
* @remarks
|
||||
* Represents all AI interactions for a 24-hour period, including:
|
||||
* - Total token counts across all models
|
||||
* - Total cost in USD
|
||||
* - Per-model breakdowns
|
||||
* - List of models used
|
||||
*
|
||||
* Date format is ISO 8601 (YYYY-MM-DD).
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const dailyData: DailyData = {
|
||||
* date: '2025-01-15',
|
||||
* inputTokens: 500000,
|
||||
* outputTokens: 250000,
|
||||
* cacheCreationTokens: 10000,
|
||||
* cacheReadTokens: 100000,
|
||||
* totalTokens: 860000,
|
||||
* totalCost: 8.50,
|
||||
* modelsUsed: ['claude-sonnet-4-20250514'],
|
||||
* modelBreakdowns: [...]
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface DailyData {
|
||||
/** Date in ISO 8601 format (YYYY-MM-DD) */
|
||||
date: string
|
||||
/** Total input tokens for the day */
|
||||
inputTokens: number
|
||||
/** Total output tokens for the day */
|
||||
outputTokens: number
|
||||
/** Total cache creation tokens for the day */
|
||||
cacheCreationTokens: number
|
||||
/** Total cache read tokens for the day */
|
||||
cacheReadTokens: number
|
||||
/** Sum of all token types */
|
||||
totalTokens: number
|
||||
/** Total cost in USD for the day */
|
||||
totalCost: number
|
||||
/** List of model identifiers used this day */
|
||||
modelsUsed: string[]
|
||||
/** Per-model usage breakdowns */
|
||||
modelBreakdowns: ModelBreakdown[]
|
||||
}
|
||||
|
||||
/**
|
||||
* Aggregated totals across all time periods.
|
||||
*
|
||||
* @remarks
|
||||
* Represents cumulative usage metrics, typically used for:
|
||||
* - All-time totals
|
||||
* - Custom date range totals
|
||||
* - Filtered subset totals
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const totals: Totals = {
|
||||
* inputTokens: 15000000,
|
||||
* outputTokens: 7500000,
|
||||
* cacheCreationTokens: 100000,
|
||||
* cacheReadTokens: 1000000,
|
||||
* totalCost: 250.00,
|
||||
* totalTokens: 23600000
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface Totals {
|
||||
/** Cumulative input tokens */
|
||||
inputTokens: number
|
||||
/** Cumulative output tokens */
|
||||
outputTokens: number
|
||||
/** Cumulative cache creation tokens */
|
||||
cacheCreationTokens: number
|
||||
/** Cumulative cache read tokens */
|
||||
cacheReadTokens: number
|
||||
/** Cumulative cost in USD */
|
||||
totalCost: number
|
||||
/** Sum of all cumulative tokens */
|
||||
totalTokens: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Complete AI usage dataset with daily breakdowns and totals.
|
||||
*
|
||||
* @remarks
|
||||
* Primary data structure for AI analytics, containing:
|
||||
* - Daily usage history
|
||||
* - Aggregate totals
|
||||
*
|
||||
* Typically loaded from JSON data files or API responses.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const data: CCData = {
|
||||
* daily: [...], // Array of DailyData
|
||||
* totals: {
|
||||
* inputTokens: 15000000,
|
||||
* outputTokens: 7500000,
|
||||
* // ... other totals
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface CCData {
|
||||
/** Array of daily usage data, typically sorted chronologically */
|
||||
daily: DailyData[]
|
||||
/** Aggregated totals across all daily data */
|
||||
totals: Totals
|
||||
}
|
||||
|
||||
/**
|
||||
* Extended AI usage data supporting multiple sources (Claude Code, Codex, etc.).
|
||||
*
|
||||
* @remarks
|
||||
* Used for dashboards that display multiple AI tool usages side-by-side.
|
||||
* Each tool can have its own daily history and totals.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const extended: ExtendedCCData = {
|
||||
* totals: { ... }, // Combined totals
|
||||
* claudeCode: {
|
||||
* daily: [...],
|
||||
* totals: { ... }
|
||||
* },
|
||||
* codex: {
|
||||
* daily: [...],
|
||||
* totals: { ... }
|
||||
* }
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface ExtendedCCData {
|
||||
/** Combined totals across all sources (optional) */
|
||||
totals?: Totals
|
||||
/** Claude Code usage data */
|
||||
claudeCode?: {
|
||||
daily: DailyData[]
|
||||
totals: Totals
|
||||
}
|
||||
/** Codex usage data */
|
||||
codex?: {
|
||||
daily: DailyData[]
|
||||
totals: Totals
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Time range selector keys for filtering AI usage data.
|
||||
*
|
||||
* @remarks
|
||||
* Used in dropdown menus and filters to select predefined time ranges:
|
||||
* - '7d': Last 7 days
|
||||
* - '1m': Last 1 month
|
||||
* - '3m': Last 3 months
|
||||
* - '6m': Last 6 months
|
||||
* - '1y': Last 1 year
|
||||
* - 'all': All available data
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* function filterByRange(data: DailyData[], range: TimeRangeKey) {
|
||||
* // Implementation
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export type TimeRangeKey = '7d' | '1m' | '3m' | '6m' | '1y' | 'all'
|
||||
|
||||
/**
|
||||
* Single day cell data for heatmap visualization.
|
||||
*
|
||||
* @remarks
|
||||
* Contains all data needed to render one cell in a GitHub-style contribution heatmap:
|
||||
* - Date information
|
||||
* - Usage metrics (tokens, cost)
|
||||
* - Display formatting
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const heatmapDay: HeatmapDay = {
|
||||
* date: '2025-01-15',
|
||||
* value: 8.50,
|
||||
* tokens: 860000,
|
||||
* cost: 8.50,
|
||||
* day: 1, // Monday
|
||||
* formattedDate: 'Jan 15, 2025'
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface HeatmapDay {
|
||||
/** Date in ISO 8601 format (YYYY-MM-DD) */
|
||||
date: string
|
||||
/** Primary value for heatmap intensity (typically cost) */
|
||||
value: number
|
||||
/** Total tokens for tooltip display */
|
||||
tokens: number
|
||||
/** Total cost for tooltip display */
|
||||
cost: number
|
||||
/** Day of week (0 = Sunday, 6 = Saturday) */
|
||||
day: number
|
||||
/** Human-readable date string for tooltips */
|
||||
formattedDate: string
|
||||
}
|
||||
|
||||
/**
|
||||
* Daily data extended with trend analysis for chart visualizations.
|
||||
*
|
||||
* @remarks
|
||||
* Extends {@link DailyData} with:
|
||||
* - Linear regression trend lines
|
||||
* - Normalized token values for charting
|
||||
*
|
||||
* Used for displaying trend overlays on usage charts.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const trendData: DailyDataWithTrend = {
|
||||
* ...dailyData,
|
||||
* costTrend: 8.75, // Predicted cost from regression
|
||||
* tokensTrend: 0.9, // Predicted tokens in millions
|
||||
* inputTokensNormalized: 500, // Input tokens / 1000
|
||||
* outputTokensNormalized: 250, // Output tokens / 1000
|
||||
* cacheTokensNormalized: 0.11 // Cache tokens / 1000000
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface DailyDataWithTrend extends DailyData {
|
||||
/** Predicted cost from linear regression (null if not enough data) */
|
||||
costTrend: number | null
|
||||
/** Predicted tokens in millions from linear regression (null if not enough data) */
|
||||
tokensTrend: number | null
|
||||
/** Input tokens divided by 1000 for chart display */
|
||||
inputTokensNormalized: number
|
||||
/** Output tokens divided by 1000 for chart display */
|
||||
outputTokensNormalized: number
|
||||
/** Cache tokens divided by 1000000 for chart display */
|
||||
cacheTokensNormalized: number
|
||||
}
|
||||
|
||||
/**
|
||||
* Model usage statistics for pie/bar charts.
|
||||
*
|
||||
* @remarks
|
||||
* Represents usage distribution across different AI models.
|
||||
* Includes both absolute values and percentages for visualization.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const usage: ModelUsage = {
|
||||
* name: 'Claude Sonnet 4',
|
||||
* value: 125.50,
|
||||
* percentage: 65.2
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface ModelUsage {
|
||||
/** Human-readable model name */
|
||||
name: string
|
||||
/** Total cost or usage value */
|
||||
value: number
|
||||
/** Percentage of total usage (optional) */
|
||||
percentage?: number
|
||||
/** Allow additional properties for chart libraries */
|
||||
[key: string]: string | number | undefined
|
||||
}
|
||||
|
||||
/**
|
||||
* Token type usage statistics for composition charts.
|
||||
*
|
||||
* @remarks
|
||||
* Breaks down usage by token type (input, output, cache creation, cache read).
|
||||
* Used for pie charts showing token distribution.
|
||||
*
|
||||
* @example
|
||||
* ```ts
|
||||
* const tokenUsage: TokenTypeUsage = {
|
||||
* name: 'Input',
|
||||
* value: 15000000,
|
||||
* percentage: 63.5
|
||||
* }
|
||||
* ```
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export interface TokenTypeUsage {
|
||||
/** Token type name ('Input', 'Output', 'Cache Creation', 'Cache Read') */
|
||||
name: string
|
||||
/** Total token count */
|
||||
value: number
|
||||
/** Percentage of total tokens (optional) */
|
||||
percentage?: number
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue