cursor-usage 0.1.0

package/dist/commands.js

@@ -0,0 +1,273 @@
+/**
+ * CLI command handlers
+ */
+import { fetchUsageEvents, groupByDay, calculateDailyStats, groupByMonth, calculateMonthlyStats, formatMonthlyStatsTable, groupByWeek, calculateWeeklyStats, formatWeeklyStatsTable, calculateModelBreakdown, formatModelBreakdownTable, } from './event-loader';
+import { createTable } from './table-formatter';
+import { logger } from './logger';
+/**
+ * Convert stats to JSON
+ */
+export function statsToJSON(command, stats, events, options = {}) {
+    const totalTokens = events.reduce((sum, e) => sum + e.tokens, 0);
+    const totalCost = events.reduce((sum, e) => sum + (e.cost || 0), 0);
+    const totalEvents = events.length;
+    const data = {
+        command,
+        generatedAt: new Date().toISOString(),
+        period: options.period || command,
+        timeRange: options.timeRange,
+        summary: {
+            totalEvents,
+            totalTokens,
+            totalCost: parseFloat(totalCost.toFixed(2)),
+        },
+        data: stats,
+    };
+    if (options.breakdown) {
+        const breakdown = calculateModelBreakdown(events);
+        data.breakdown = Array.from(breakdown.values()).map((model) => ({
+            model: model.model,
+            count: model.count,
+            totalTokens: model.totalTokens,
+            inputTokens: model.inputTokens,
+            outputTokens: model.outputTokens,
+            totalCost: parseFloat(model.totalCost.toFixed(2)),
+            tokenPercent: parseFloat(((model.totalTokens / totalTokens) * 100).toFixed(2)),
+            costPercent: parseFloat(((model.totalCost / totalCost) * 100).toFixed(2)),
+        }));
+    }
+    return JSON.stringify(data, null, 2);
+}
+/**
+ * Display model breakdown
+ */
+function displayBreakdown(events, title = 'MODEL BREAKDOWN') {
+    const breakdown = calculateModelBreakdown(events);
+    const totalTokens = events.reduce((sum, e) => sum + e.tokens, 0);
+    const totalCost = events.reduce((sum, e) => sum + (e.cost || 0), 0);
+    logger.log('\n' + '='.repeat(100));
+    logger.log(title);
+    logger.log('='.repeat(100) + '\n');
+    const tableData = formatModelBreakdownTable(breakdown, totalTokens, totalCost);
+    const table = createTable(['Model', 'Events', 'Total Tokens', 'Cost', 'Token %', 'Cost %'], tableData);
+    logger.log(table + '\n');
+}
+/**
+ * Show daily usage report for a date range
+ */
+export async function showDailyReport(credentials, days = 7, options = {}, outputJson = false) {
+    let startDate = options.startDate;
+    let endDate = options.endDate;
+    if (!startDate || !endDate) {
+        endDate = endDate || new Date();
+        startDate = startDate || new Date();
+        startDate.setDate(startDate.getDate() - days);
+        // Set to start of day
+        startDate.setHours(0, 0, 0, 0);
+        endDate.setHours(23, 59, 59, 999);
+    }
+    const events = await fetchUsageEvents(credentials, startDate, endDate);
+    if (events.length === 0) {
+        logger.warn('No usage events found for this period');
+        return;
+    }
+    logger.log('');
+    // Group and calculate stats
+    const grouped = groupByDay(events);
+    const stats = calculateDailyStats(grouped);
+    // Display table
+    logger.log('\n' + '='.repeat(100));
+    logger.log(`DAILY USAGE REPORT (Last ${days} days)`);
+    logger.log('='.repeat(100) + '\n');
+    const tableData = stats.map((day) => {
+        const modelList = Array.from(day.models.entries())
+            .map(([model, count]) => `${model}(${count})`)
+            .join(', ');
+        return [
+            day.date,
+            day.eventCount.toString(),
+            day.totalTokens.toLocaleString(),
+            day.inputTokens.toLocaleString(),
+            day.outputTokens.toLocaleString(),
+            `$${day.totalCost.toFixed(2)}`,
+            modelList || 'N/A',
+        ];
+    });
+    const table = createTable(['Date', 'Events', 'Total Tokens', 'Input', 'Output', 'Cost', 'Models'], tableData);
+    logger.log(table);
+    // Summary
+    const totalEvents = stats.reduce((sum, day) => sum + day.eventCount, 0);
+    const totalTokens = stats.reduce((sum, day) => sum + day.totalTokens, 0);
+    const totalCost = stats.reduce((sum, day) => sum + day.totalCost, 0);
+    logger.log('\n' + '='.repeat(100));
+    logger.log('SUMMARY');
+    logger.log('='.repeat(100));
+    logger.log(`Total Events: ${totalEvents}`);
+    logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
+    logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
+    logger.log('='.repeat(100) + '\n');
+    // Show breakdown if requested
+    if (options.breakdown) {
+        displayBreakdown(events, 'PER-MODEL BREAKDOWN');
+    }
+    // Output JSON if requested
+    if (outputJson) {
+        const jsonOutput = statsToJSON('daily', stats, events, { breakdown: options.breakdown, period: `last ${days} days` });
+        console.log(jsonOutput);
+    }
+}
+/**
+ * Show monthly usage report
+ */
+export async function showMonthlyReport(credentials, months = 3, options = {}, outputJson = false) {
+    let startDate = options.startDate;
+    let endDate = options.endDate;
+    if (!startDate || !endDate) {
+        endDate = endDate || new Date();
+        startDate = startDate || new Date();
+        startDate.setMonth(startDate.getMonth() - months);
+        // Set to start of month
+        startDate.setDate(1);
+        startDate.setHours(0, 0, 0, 0);
+        endDate.setHours(23, 59, 59, 999);
+    }
+    const events = await fetchUsageEvents(credentials, startDate, endDate);
+    if (events.length === 0) {
+        logger.warn('No usage events found for this period');
+        return;
+    }
+    logger.log('');
+    // Group and calculate stats
+    const grouped = groupByMonth(events);
+    const stats = calculateMonthlyStats(grouped);
+    // Display table
+    logger.log('\n' + '='.repeat(100));
+    logger.log(`MONTHLY USAGE REPORT (Last ${months} months)`);
+    logger.log('='.repeat(100) + '\n');
+    const tableData = formatMonthlyStatsTable(stats);
+    const table = createTable(['Month', 'Events', 'Total Tokens', 'Input', 'Output', 'Cost', 'Models'], tableData);
+    logger.log(table);
+    // Summary
+    const totalEvents = stats.reduce((sum, month) => sum + month.eventCount, 0);
+    const totalTokens = stats.reduce((sum, month) => sum + month.totalTokens, 0);
+    const totalCost = stats.reduce((sum, month) => sum + month.totalCost, 0);
+    logger.log('\n' + '='.repeat(100));
+    logger.log('SUMMARY');
+    logger.log('='.repeat(100));
+    logger.log(`Total Events: ${totalEvents}`);
+    logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
+    logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
+    logger.log(`Average per month: ${(totalTokens / Math.max(1, stats.length)).toLocaleString()} tokens, $${(totalCost / Math.max(1, stats.length)).toFixed(2)}`);
+    logger.log('='.repeat(100) + '\n');
+    // Show breakdown if requested
+    if (options.breakdown) {
+        displayBreakdown(events, 'PER-MODEL BREAKDOWN');
+    }
+    // Output JSON if requested
+    if (outputJson) {
+        const jsonOutput = statsToJSON('monthly', stats, events, { breakdown: options.breakdown, period: `last ${months} months` });
+        console.log(jsonOutput);
+    }
+}
+/**
+ * Show weekly usage report
+ */
+export async function showWeeklyReport(credentials, weeks = 4, options = {}, outputJson = false) {
+    let startDate = options.startDate;
+    let endDate = options.endDate;
+    if (!startDate || !endDate) {
+        endDate = endDate || new Date();
+        startDate = startDate || new Date();
+        startDate.setDate(startDate.getDate() - weeks * 7);
+        // Set to start of day
+        startDate.setHours(0, 0, 0, 0);
+        endDate.setHours(23, 59, 59, 999);
+    }
+    const events = await fetchUsageEvents(credentials, startDate, endDate);
+    if (events.length === 0) {
+        logger.warn('No usage events found for this period');
+        return;
+    }
+    logger.log('');
+    // Group and calculate stats
+    const grouped = groupByWeek(events);
+    const stats = calculateWeeklyStats(grouped);
+    // Display table
+    logger.log('\n' + '='.repeat(120));
+    logger.log(`WEEKLY USAGE REPORT (Last ${weeks} weeks)`);
+    logger.log('='.repeat(120) + '\n');
+    const tableData = formatWeeklyStatsTable(stats);
+    const table = createTable(['Week', 'Events', 'Total Tokens', 'Input', 'Output', 'Cost', 'Models'], tableData);
+    logger.log(table);
+    // Summary
+    const totalEvents = stats.reduce((sum, week) => sum + week.eventCount, 0);
+    const totalTokens = stats.reduce((sum, week) => sum + week.totalTokens, 0);
+    const totalCost = stats.reduce((sum, week) => sum + week.totalCost, 0);
+    logger.log('\n' + '='.repeat(120));
+    logger.log('SUMMARY');
+    logger.log('='.repeat(120));
+    logger.log(`Total Events: ${totalEvents}`);
+    logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
+    logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
+    logger.log(`Average per week: ${(totalTokens / Math.max(1, stats.length)).toLocaleString()} tokens, $${(totalCost / Math.max(1, stats.length)).toFixed(2)}`);
+    logger.log('='.repeat(120) + '\n');
+    // Show breakdown if requested
+    if (options.breakdown) {
+        displayBreakdown(events, 'PER-MODEL BREAKDOWN');
+    }
+    // Output JSON if requested
+    if (outputJson) {
+        const jsonOutput = statsToJSON('weekly', stats, events, { breakdown: options.breakdown, period: `last ${weeks} weeks` });
+        console.log(jsonOutput);
+    }
+}
+/**
+ * Show usage for a specific date
+ */
+export async function showDateReport(credentials, date, options = {}, outputJson = false) {
+    const startDate = new Date(date);
+    startDate.setHours(0, 0, 0, 0);
+    const endDate = new Date(date);
+    endDate.setHours(23, 59, 59, 999);
+    const events = await fetchUsageEvents(credentials, startDate, endDate);
+    if (events.length === 0) {
+        logger.warn('No usage events found for this date');
+        return;
+    }
+    logger.log('');
+    // Display detailed events
+    logger.log('\n' + '='.repeat(120));
+    logger.log(`USAGE EVENTS FOR ${date.toDateString()}`);
+    logger.log('='.repeat(120) + '\n');
+    const tableData = events.map((event) => {
+        const timestamp = new Date(event.timestamp).toLocaleTimeString();
+        return [
+            timestamp,
+            event.model,
+            event.type,
+            event.inputTokens.toLocaleString(),
+            event.outputTokens.toLocaleString(),
+            event.tokens.toLocaleString(),
+            `$${event.cost?.toFixed(4) || '0.0000'}`,
+        ];
+    });
+    const table = createTable(['Time', 'Model', 'Type', 'Input Tokens', 'Output Tokens', 'Total Tokens', 'Cost'], tableData);
+    logger.log(table);
+    // Summary
+    const totalTokens = events.reduce((sum, e) => sum + e.tokens, 0);
+    const totalCost = events.reduce((sum, e) => sum + (e.cost || 0), 0);
+    logger.log('\n' + '='.repeat(120));
+    logger.log(`Total Events: ${events.length}`);
+    logger.log(`Total Tokens: ${totalTokens.toLocaleString()}`);
+    logger.log(`Total Cost: $${totalCost.toFixed(2)}`);
+    logger.log('='.repeat(120) + '\n');
+    // Show breakdown if requested
+    if (options.breakdown) {
+        displayBreakdown(events, 'PER-MODEL BREAKDOWN');
+    }
+    // Output JSON if requested
+    if (outputJson) {
+        const jsonOutput = statsToJSON('today', events.map((e, i) => ({ ...e, eventIndex: i })), events, { breakdown: options.breakdown, period: 'today' });
+        console.log(jsonOutput);
+    }
+}

package/dist/data-loader.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Data loading utilities for Cursor usage analysis
+ * Extracts credentials from local database and fetches usage data from API
+ */
+import type { CursorCredentials, UsageSummary } from './_types';
+/**
+ * Extract Cursor credentials from local database
+ */
+export declare function getCursorCredentials(): Promise<CursorCredentials | null>;
+/**
+ * Fetch usage data from Cursor API
+ */
+export declare function fetchUsageData(credentials: CursorCredentials): Promise<UsageSummary | null>;

package/dist/data-loader.js

@@ -0,0 +1,134 @@
+/**
+ * Data loading utilities for Cursor usage analysis
+ * Extracts credentials from local database and fetches usage data from API
+ */
+import { readFileSync } from 'node:fs';
+import { CURSOR_API_URL, CURSOR_DB_PATH, DB_KEY_ACCESS_TOKEN, DB_KEY_EMAIL, DB_KEY_MEMBERSHIP, DB_KEY_STATSIG_BOOTSTRAP, DEFAULT_TIMEOUT, USER_AGENT, } from './_consts';
+import { logger } from './logger';
+import initSqlJs from 'sql.js';
+let sqlJs = null;
+/**
+ * Initialize SQL.js
+ */
+async function initSql() {
+    if (!sqlJs) {
+        sqlJs = await initSqlJs();
+    }
+    return sqlJs;
+}
+/**
+ * Query database value
+ */
+function queryDB(db, key) {
+    try {
+        const stmt = db.prepare(`SELECT value FROM ItemTable WHERE key = ?`);
+        stmt.bind([key]);
+        if (stmt.step()) {
+            const row = stmt.getAsObject();
+            return row.value || null;
+        }
+        stmt.free();
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract Cursor credentials from local database
+ */
+export async function getCursorCredentials() {
+    try {
+        const sql = await initSql();
+        const data = readFileSync(CURSOR_DB_PATH);
+        const db = new sql.Database(data);
+        // Get user ID from statsigBootstrap
+        let userId = null;
+        const bootstrapValue = queryDB(db, DB_KEY_STATSIG_BOOTSTRAP);
+        if (bootstrapValue) {
+            try {
+                const parsed = JSON.parse(bootstrapValue);
+                userId = parsed?.user?.userID;
+            }
+            catch (e) {
+                logger.warn('Failed to extract user ID from statsigBootstrap');
+            }
+        }
+        // Get access token
+        const accessToken = queryDB(db, DB_KEY_ACCESS_TOKEN);
+        // Get email
+        const email = queryDB(db, DB_KEY_EMAIL) || undefined;
+        // Get membership
+        const membership = queryDB(db, DB_KEY_MEMBERSHIP) || undefined;
+        db.close();
+        if (!userId) {
+            logger.error('Could not extract user ID from database');
+            return null;
+        }
+        if (!accessToken) {
+            logger.error('Could not extract access token from database');
+            return null;
+        }
+        return {
+            userId,
+            accessToken,
+            email,
+            membership,
+        };
+    }
+    catch (error) {
+        logger.error(`Error reading database: ${String(error)}`);
+        return null;
+    }
+}
+/**
+ * Fetch usage data from Cursor API
+ */
+export async function fetchUsageData(credentials) {
+    try {
+        const sessionToken = `${credentials.userId}::${credentials.accessToken}`;
+        const headers = {
+            Accept: 'application/json',
+            'Content-Type': 'application/json',
+            'User-Agent': USER_AGENT,
+        };
+        const cookieHeader = `WorkosCursorSessionToken=${encodeURIComponent(sessionToken)}`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
+        const response = await fetch(CURSOR_API_URL, {
+            method: 'GET',
+            headers: {
+                ...headers,
+                Cookie: cookieHeader,
+            },
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            logger.error(`API request failed with status ${response.status}: ${response.statusText}`);
+            return null;
+        }
+        const data = (await response.json());
+        return validateAndParse(data);
+    }
+    catch (error) {
+        logger.error(`Error fetching usage data: ${String(error)}`);
+        return null;
+    }
+}
+/**
+ * Validate and parse API response
+ */
+function validateAndParse(data) {
+    try {
+        if (typeof data !== 'object' || data === null) {
+            logger.error('Invalid API response format');
+            return null;
+        }
+        return data;
+    }
+    catch (error) {
+        logger.error(`Error parsing API response: ${String(error)}`);
+        return null;
+    }
+}

package/dist/event-loader.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Event loading utilities for detailed usage analysis
+ * Fetches granular usage events for building daily/weekly reports
+ */
+import type { CursorCredentials } from './_types';
+export interface UsageEvent {
+    id: string;
+    timestamp: number;
+    model: string;
+    tokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheWriteTokens: number;
+    cacheReadTokens: number;
+    type: string;
+    kind: string;
+    cost: number;
+    maxMode: boolean;
+}
+export interface EventsResponse {
+    events: UsageEvent[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/**
+ * Fetch usage events for a date range
+ */
+export declare function fetchUsageEvents(credentials: CursorCredentials, startDate: Date, endDate: Date, pageSize?: number): Promise<UsageEvent[]>;
+/**
+ * Group events by day
+ */
+export declare function groupByDay(events: UsageEvent[]): Map<string, UsageEvent[]>;
+/**
+ * Calculate daily statistics
+ */
+export interface DailyStats {
+    date: string;
+    eventCount: number;
+    totalTokens: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalCost: number;
+    models: Map<string, number>;
+}
+export declare function calculateDailyStats(groupedEvents: Map<string, UsageEvent[]>): DailyStats[];
+/**
+ * Format daily stats for table display
+ */
+export declare function formatDailyStatsTable(stats: DailyStats[]): string[][];
+/**
+ * Group events by month
+ */
+export declare function groupByMonth(events: UsageEvent[]): Map<string, UsageEvent[]>;
+/**
+ * Calculate monthly statistics
+ */
+export declare function calculateMonthlyStats(groupedEvents: Map<string, UsageEvent[]>): any[];
+/**
+ * Format monthly stats for table display
+ */
+export declare function formatMonthlyStatsTable(stats: any[]): string[][];
+/**
+ * Calculate per-model breakdown
+ */
+export declare function calculateModelBreakdown(events: UsageEvent[]): Map<string, any>;
+/**
+ * Format model breakdown for display
+ */
+export declare function formatModelBreakdownTable(breakdown: Map<string, any>, totalTokens: number, totalCost: number): string[][];
+/**
+ * Group events by week
+ */
+export declare function groupByWeek(events: UsageEvent[]): Map<string, UsageEvent[]>;
+/**
+ * Calculate weekly statistics
+ */
+export declare function calculateWeeklyStats(groupedEvents: Map<string, UsageEvent[]>): any[];
+/**
+ * Format weekly stats for table display
+ */
+export declare function formatWeeklyStatsTable(stats: any[]): string[][];