ccusage 11.0.0 → 11.0.1

package/dist/{data-loader-DPQaq8_n.d.ts → data-loader-dbZm5kOW.d.ts}

@@ -1,6 +1,10 @@
-import { ArraySchema, CostMode, InferOutput, NumberSchema, ObjectSchema, OptionalSchema, PricingFetcher, RegexAction, SchemaWithPipe, SortOrder, StringSchema } from "./pricing-fetcher-BkSZh4lR.js";
+import { ArraySchema, CostMode, InferOutput, NumberSchema, ObjectSchema, OptionalSchema, PricingFetcher, RegexAction, SchemaWithPipe, SortOrder, StringSchema } from "./pricing-fetcher-DHaTs-k2.js";
 
-//#region src/five-hour-blocks.internal.d.ts
+//#region src/session-blocks.internal.d.ts
+
+/**
+ * Represents a single usage data entry loaded from JSONL files
+ */
 type LoadedUsageEntry = {
   timestamp: Date;
   usage: {
@@ -13,24 +17,33 @@ type LoadedUsageEntry = {
   model: string;
   version?: string;
 };
+/**
+ * Aggregated token counts for different token types
+ */
 type TokenCounts = {
   inputTokens: number;
   outputTokens: number;
   cacheCreationInputTokens: number;
   cacheReadInputTokens: number;
 };
-type FiveHourBlock = {
-  id: string;
+/**
+ * Represents a session block (typically 5-hour billing period) with usage data
+ */
+type SessionBlock = {
+  id: string; // ISO string of block start time
   startTime: Date;
-  endTime: Date;
-  actualEndTime?: Date;
+  endTime: Date; // startTime + 5 hours (for normal blocks) or gap end time (for gap blocks)
+  actualEndTime?: Date; // Last activity in block
   isActive: boolean;
-  isGap?: boolean;
+  isGap?: boolean; // True if this is a gap block
   entries: LoadedUsageEntry[];
   tokenCounts: TokenCounts;
   costUSD: number;
   models: string[];
 };
+/**
+ * Represents usage burn rate calculations
+ */
 //#endregion
 //#region src/data-loader.d.ts
 /**
@@ -38,7 +51,10 @@ type FiveHourBlock = {
  * Uses environment variable CLAUDE_CONFIG_DIR if set, otherwise defaults to ~/.claude
  */
 declare function getDefaultClaudePath(): string;
-declare const UsageDataSchema: ObjectSchema<{
+/**
+ * Valibot schema for validating Claude usage data from JSONL files
+ */
+declare const usageDataSchema: ObjectSchema<{
   readonly timestamp: StringSchema<undefined>;
   readonly version: OptionalSchema<StringSchema<undefined>, undefined>;
   readonly message: ObjectSchema<{
@@ -54,8 +70,14 @@ declare const UsageDataSchema: ObjectSchema<{
   readonly costUSD: OptionalSchema<NumberSchema<undefined>, undefined>;
   readonly requestId: OptionalSchema<StringSchema<undefined>, undefined>;
 }, undefined>;
-type UsageData = InferOutput<typeof UsageDataSchema>;
-declare const ModelBreakdownSchema: ObjectSchema<{
+/**
+ * Type definition for Claude usage data entries from JSONL files
+ */
+type UsageData = InferOutput<typeof usageDataSchema>;
+/**
+ * Valibot schema for model-specific usage breakdown data
+ */
+declare const modelBreakdownSchema: ObjectSchema<{
   readonly modelName: StringSchema<undefined>;
   readonly inputTokens: NumberSchema<undefined>;
   readonly outputTokens: NumberSchema<undefined>;
@@ -63,8 +85,14 @@ declare const ModelBreakdownSchema: ObjectSchema<{
   readonly cacheReadTokens: NumberSchema<undefined>;
   readonly cost: NumberSchema<undefined>;
 }, undefined>;
-type ModelBreakdown = InferOutput<typeof ModelBreakdownSchema>;
-declare const DailyUsageSchema: ObjectSchema<{
+/**
+ * Type definition for model-specific usage breakdown
+ */
+type ModelBreakdown = InferOutput<typeof modelBreakdownSchema>;
+/**
+ * Valibot schema for daily usage aggregation data
+ */
+declare const dailyUsageSchema: ObjectSchema<{
   readonly date: SchemaWithPipe<readonly [StringSchema<undefined>, RegexAction<string, undefined>]>;
   readonly inputTokens: NumberSchema<undefined>;
   readonly outputTokens: NumberSchema<undefined>;
@@ -81,8 +109,14 @@ declare const DailyUsageSchema: ObjectSchema<{
     readonly cost: NumberSchema<undefined>;
   }, undefined>, undefined>;
 }, undefined>;
-type DailyUsage = InferOutput<typeof DailyUsageSchema>;
-declare const SessionUsageSchema: ObjectSchema<{
+/**
+ * Type definition for daily usage aggregation
+ */
+type DailyUsage = InferOutput<typeof dailyUsageSchema>;
+/**
+ * Valibot schema for session-based usage aggregation data
+ */
+declare const sessionUsageSchema: ObjectSchema<{
   readonly sessionId: StringSchema<undefined>;
   readonly projectPath: StringSchema<undefined>;
   readonly inputTokens: NumberSchema<undefined>;
@@ -102,8 +136,14 @@ declare const SessionUsageSchema: ObjectSchema<{
     readonly cost: NumberSchema<undefined>;
   }, undefined>, undefined>;
 }, undefined>;
-type SessionUsage = InferOutput<typeof SessionUsageSchema>;
-declare const MonthlyUsageSchema: ObjectSchema<{
+/**
+ * Type definition for session-based usage aggregation
+ */
+type SessionUsage = InferOutput<typeof sessionUsageSchema>;
+/**
+ * Valibot schema for monthly usage aggregation data
+ */
+declare const monthlyUsageSchema: ObjectSchema<{
   readonly month: SchemaWithPipe<readonly [StringSchema<undefined>, RegexAction<string, undefined>]>;
   readonly inputTokens: NumberSchema<undefined>;
   readonly outputTokens: NumberSchema<undefined>;
@@ -120,8 +160,21 @@ declare const MonthlyUsageSchema: ObjectSchema<{
     readonly cost: NumberSchema<undefined>;
   }, undefined>, undefined>;
 }, undefined>;
-type MonthlyUsage = InferOutput<typeof MonthlyUsageSchema>;
+/**
+ * Type definition for monthly usage aggregation
+ */
+type MonthlyUsage = InferOutput<typeof monthlyUsageSchema>;
+/**
+ * Formats a date string to YYYY-MM-DD format
+ * @param dateStr - Input date string
+ * @returns Formatted date string in YYYY-MM-DD format
+ */
 declare function formatDate(dateStr: string): string;
+/**
+ * Formats a date string to compact format with year on first line and month-day on second
+ * @param dateStr - Input date string
+ * @returns Formatted date string with newline separator (YYYY\nMM-DD)
+ */
 declare function formatDateCompact(dateStr: string): string;
 /**
  * Create a unique identifier for deduplication using message ID and request ID
@@ -137,20 +190,58 @@ declare function getEarliestTimestamp(filePath: string): Promise<Date | null>;
  * Files without valid timestamps are placed at the end
  */
 declare function sortFilesByTimestamp(files: string[]): Promise<string[]>;
+/**
+ * Calculates cost for a single usage data entry based on the specified cost calculation mode
+ * @param data - Usage data entry
+ * @param mode - Cost calculation mode (auto, calculate, or display)
+ * @param fetcher - Pricing fetcher instance for calculating costs from tokens
+ * @returns Calculated cost in USD
+ */
 declare function calculateCostForEntry(data: UsageData, mode: CostMode, fetcher: PricingFetcher): Promise<number>;
+/**
+ * Date range filter for limiting usage data by date
+ */
 type DateFilter = {
-  since?: string;
-  until?: string;
+  since?: string; // YYYYMMDD format
+  until?: string; // YYYYMMDD format
 };
+/**
+ * Configuration options for loading usage data
+ */
 type LoadOptions = {
-  claudePath?: string;
-  mode?: CostMode;
-  order?: SortOrder;
-  offline?: boolean;
+  claudePath?: string; // Custom path to Claude data directory
+  mode?: CostMode; // Cost calculation mode
+  order?: SortOrder; // Sort order for dates
+  offline?: boolean; // Use offline mode for pricing
+  sessionDurationHours?: number; // Session block duration in hours
 } & DateFilter;
+/**
+ * Loads and aggregates Claude usage data by day
+ * Processes all JSONL files in the Claude projects directory and groups usage by date
+ * @param options - Optional configuration for loading and filtering data
+ * @returns Array of daily usage summaries sorted by date
+ */
 declare function loadDailyUsageData(options?: LoadOptions): Promise<DailyUsage[]>;
+/**
+ * Loads and aggregates Claude usage data by session
+ * Groups usage data by project path and session ID based on file structure
+ * @param options - Optional configuration for loading and filtering data
+ * @returns Array of session usage summaries sorted by last activity
+ */
 declare function loadSessionData(options?: LoadOptions): Promise<SessionUsage[]>;
+/**
+ * Loads and aggregates Claude usage data by month
+ * Uses daily usage data as the source and groups by month
+ * @param options - Optional configuration for loading and filtering data
+ * @returns Array of monthly usage summaries sorted by month
+ */
 declare function loadMonthlyUsageData(options?: LoadOptions): Promise<MonthlyUsage[]>;
-declare function loadFiveHourBlockData(options?: LoadOptions): Promise<FiveHourBlock[]>;
+/**
+ * Loads usage data and organizes it into session blocks (typically 5-hour billing periods)
+ * Processes all usage data and groups it into time-based blocks for billing analysis
+ * @param options - Optional configuration including session duration and filtering
+ * @returns Array of session blocks with usage and cost information
+ */
+declare function loadSessionBlockData(options?: LoadOptions): Promise<SessionBlock[]>;
 //#endregion
-export { DailyUsage, DailyUsageSchema, DateFilter, LoadOptions, ModelBreakdown, ModelBreakdownSchema, MonthlyUsage, MonthlyUsageSchema, SessionUsage, SessionUsageSchema, UsageData, UsageDataSchema, calculateCostForEntry, createUniqueHash, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadFiveHourBlockData, loadMonthlyUsageData, loadSessionData, sortFilesByTimestamp };
+export { DailyUsage, DateFilter, LoadOptions, ModelBreakdown, MonthlyUsage, SessionUsage, UsageData, calculateCostForEntry, createUniqueHash, dailyUsageSchema, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadMonthlyUsageData, loadSessionBlockData, loadSessionData, modelBreakdownSchema, monthlyUsageSchema, sessionUsageSchema, sortFilesByTimestamp, usageDataSchema };

package/dist/data-loader.d.ts

@@ -1,3 +1,3 @@
-import "./pricing-fetcher-BkSZh4lR.js";
-import { DailyUsage, DailyUsageSchema, DateFilter, LoadOptions, ModelBreakdown, ModelBreakdownSchema, MonthlyUsage, MonthlyUsageSchema, SessionUsage, SessionUsageSchema, UsageData, UsageDataSchema, calculateCostForEntry, createUniqueHash, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadFiveHourBlockData, loadMonthlyUsageData, loadSessionData, sortFilesByTimestamp } from "./data-loader-DPQaq8_n.js";
-export { DailyUsage, DailyUsageSchema, DateFilter, LoadOptions, ModelBreakdown, ModelBreakdownSchema, MonthlyUsage, MonthlyUsageSchema, SessionUsage, SessionUsageSchema, UsageData, UsageDataSchema, calculateCostForEntry, createUniqueHash, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadFiveHourBlockData, loadMonthlyUsageData, loadSessionData, sortFilesByTimestamp };
+import "./pricing-fetcher-DHaTs-k2.js";
+import { DailyUsage, DateFilter, LoadOptions, ModelBreakdown, MonthlyUsage, SessionUsage, UsageData, calculateCostForEntry, createUniqueHash, dailyUsageSchema, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadMonthlyUsageData, loadSessionBlockData, loadSessionData, modelBreakdownSchema, monthlyUsageSchema, sessionUsageSchema, sortFilesByTimestamp, usageDataSchema } from "./data-loader-dbZm5kOW.js";
+export { DailyUsage, DateFilter, LoadOptions, ModelBreakdown, MonthlyUsage, SessionUsage, UsageData, calculateCostForEntry, createUniqueHash, dailyUsageSchema, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadMonthlyUsageData, loadSessionBlockData, loadSessionData, modelBreakdownSchema, monthlyUsageSchema, sessionUsageSchema, sortFilesByTimestamp, usageDataSchema };

package/dist/data-loader.js

@@ -1,6 +1,6 @@
-import { DailyUsageSchema, ModelBreakdownSchema, MonthlyUsageSchema, SessionUsageSchema, UsageDataSchema, calculateCostForEntry, createUniqueHash, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadFiveHourBlockData, loadMonthlyUsageData, loadSessionData, sortFilesByTimestamp } from "./data-loader-BAoqS297.js";
+import "./pricing-fetcher-BtW4MVG7.js";
+import { calculateCostForEntry, createUniqueHash, dailyUsageSchema, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadMonthlyUsageData, loadSessionBlockData, loadSessionData, modelBreakdownSchema, monthlyUsageSchema, sessionUsageSchema, sortFilesByTimestamp, usageDataSchema } from "./data-loader-BzOeJe6y.js";
 import "./dist-DCvt9hEv.js";
-import "./logger-D3WD64Tx.js";
-import "./pricing-fetcher-D-eJQBEJ.js";
+import "./logger-E_Utl_fr.js";
 
-export { DailyUsageSchema, ModelBreakdownSchema, MonthlyUsageSchema, SessionUsageSchema, UsageDataSchema, calculateCostForEntry, createUniqueHash, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadFiveHourBlockData, loadMonthlyUsageData, loadSessionData, sortFilesByTimestamp };
+export { calculateCostForEntry, createUniqueHash, dailyUsageSchema, formatDate, formatDateCompact, getDefaultClaudePath, getEarliestTimestamp, loadDailyUsageData, loadMonthlyUsageData, loadSessionBlockData, loadSessionData, modelBreakdownSchema, monthlyUsageSchema, sessionUsageSchema, sortFilesByTimestamp, usageDataSchema };

package/dist/{debug-DzFJHzM5.js → debug-CjjJciy1.js}

@@ -1,15 +1,23 @@
-import { __toESM } from "./chunk-BLXvPPr8.js";
-import { UsageDataSchema, glob, require_usingCtx } from "./data-loader-BAoqS297.js";
+import { PricingFetcher, __toESM, require_usingCtx } from "./pricing-fetcher-BtW4MVG7.js";
+import { glob, usageDataSchema } from "./data-loader-BzOeJe6y.js";
 import { safeParse } from "./dist-DCvt9hEv.js";
-import { logger } from "./logger-D3WD64Tx.js";
-import { PricingFetcher } from "./pricing-fetcher-D-eJQBEJ.js";
+import { logger } from "./logger-E_Utl_fr.js";
 import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import path from "node:path";
 
 //#region src/debug.ts
 var import_usingCtx = __toESM(require_usingCtx(), 1);
+/**
+* Threshold percentage for considering costs as matching (0.1% tolerance)
+*/
 const MATCH_THRESHOLD_PERCENT = .1;
+/**
+* Analyzes usage data to detect pricing mismatches between stored and calculated costs
+* Compares pre-calculated costUSD values with costs calculated from token usage
+* @param claudePath - Optional path to Claude data directory
+* @returns Statistics about pricing mismatches found
+*/
 async function detectMismatches(claudePath) {
 	try {
 		var _usingCtx = (0, import_usingCtx.default)();
@@ -33,7 +41,7 @@ async function detectMismatches(claudePath) {
 			const lines = content.trim().split("\n").filter((line) => line.length > 0);
 			for (const line of lines) try {
 				const parsed = JSON.parse(line);
-				const result = safeParse(UsageDataSchema, parsed);
+				const result = safeParse(usageDataSchema, parsed);
 				if (!result.success) continue;
 				const data = result.output;
 				stats.totalEntries++;
@@ -92,6 +100,11 @@ async function detectMismatches(claudePath) {
 		_usingCtx.d();
 	}
 }
+/**
+* Prints a detailed report of pricing mismatches to the console
+* @param stats - Mismatch statistics to report
+* @param sampleCount - Number of sample discrepancies to show (default: 5)
+*/
 function printMismatchReport(stats, sampleCount = 5) {
 	if (stats.entriesWithBoth === 0) {
 		logger.info("No pricing data found to analyze.");
@@ -106,7 +119,7 @@ function printMismatchReport(stats, sampleCount = 5) {
 	logger.info(`Match rate: ${matchRate.toFixed(2)}%`);
 	if (stats.mismatches > 0 && stats.modelStats.size > 0) {
 		logger.info("\n=== Model Statistics ===");
-		const sortedModels = Array.from(stats.modelStats.entries()).sort((a, b) => b[1].mismatches - a[1].mismatches);
+		const sortedModels = Array.from(stats.modelStats.entries()).sort((a$1, b) => b[1].mismatches - a$1[1].mismatches);
 		for (const [model, modelStat] of sortedModels) if (modelStat.mismatches > 0) {
 			const modelMatchRate = modelStat.matches / modelStat.total * 100;
 			logger.info(`${model}:`);
@@ -118,7 +131,7 @@ function printMismatchReport(stats, sampleCount = 5) {
 	}
 	if (stats.mismatches > 0 && stats.versionStats.size > 0) {
 		logger.info("\n=== Version Statistics ===");
-		const sortedVersions = Array.from(stats.versionStats.entries()).filter(([_, versionStat]) => versionStat.mismatches > 0).sort((a, b) => b[1].mismatches - a[1].mismatches);
+		const sortedVersions = Array.from(stats.versionStats.entries()).filter(([_, versionStat]) => versionStat.mismatches > 0).sort((a$1, b) => b[1].mismatches - a$1[1].mismatches);
 		for (const [version, versionStat] of sortedVersions) {
 			const versionMatchRate = versionStat.matches / versionStat.total * 100;
 			logger.info(`${version}:`);

package/dist/debug.d.ts

@@ -1,4 +1,7 @@
 //#region src/debug.d.ts
+/**
+ * Represents a pricing discrepancy between original and calculated costs
+ */
 type Discrepancy = {
   file: string;
   timestamp: string;
@@ -14,6 +17,9 @@ type Discrepancy = {
     cache_read_input_tokens?: number;
   };
 };
+/**
+ * Statistics about pricing mismatches across all usage data
+ */
 type MismatchStats = {
   totalEntries: number;
   entriesWithBoth: number;
@@ -33,7 +39,18 @@ type MismatchStats = {
     avgPercentDiff: number;
   }>;
 };
+/**
+ * Analyzes usage data to detect pricing mismatches between stored and calculated costs
+ * Compares pre-calculated costUSD values with costs calculated from token usage
+ * @param claudePath - Optional path to Claude data directory
+ * @returns Statistics about pricing mismatches found
+ */
 declare function detectMismatches(claudePath?: string): Promise<MismatchStats>;
+/**
+ * Prints a detailed report of pricing mismatches to the console
+ * @param stats - Mismatch statistics to report
+ * @param sampleCount - Number of sample discrepancies to show (default: 5)
+ */
 declare function printMismatchReport(stats: MismatchStats, sampleCount?: number): void;
 //#endregion
 export { detectMismatches, printMismatchReport };

package/dist/debug.js

@@ -1,7 +1,7 @@
-import "./data-loader-BAoqS297.js";
+import "./pricing-fetcher-BtW4MVG7.js";
+import "./data-loader-BzOeJe6y.js";
 import "./dist-DCvt9hEv.js";
-import "./logger-D3WD64Tx.js";
-import "./pricing-fetcher-D-eJQBEJ.js";
-import { detectMismatches, printMismatchReport } from "./debug-DzFJHzM5.js";
+import "./logger-E_Utl_fr.js";
+import { detectMismatches, printMismatchReport } from "./debug-CjjJciy1.js";
 
 export { detectMismatches, printMismatchReport };

package/dist/{effect-WSjEuzC9-DHMVzzyB.js → effect-WSjEuzC9-CZCpOgOT.js}

@@ -1,4 +1,4 @@
-import { tryImport } from "./index-CISmcbXk-CW1Gj6Ab.js";
+import { tryImport } from "./index-CISmcbXk-DpuCarFe.js";
 
 //#region node_modules/xsschema/dist/effect-WSjEuzC9.js
 const getToJsonSchemaFn = async () => {

package/dist/{esm-BU3FhOe-.js → esm-D74K9ESq.js}

@@ -1,4 +1,4 @@
-import { ZodFirstPartyTypeKind, ZodOptional } from "./types-BlyCnKwN.js";
+import { ZodFirstPartyTypeKind, ZodOptional } from "./types-5-VF7WcO.js";
 
 //#region node_modules/zod-to-json-schema/dist/esm/Options.js
 const ignoreOverride = Symbol("Let zodToJsonSchema decide on which parser to use");

package/dist/{index-CISmcbXk-CW1Gj6Ab.js → index-CISmcbXk-DpuCarFe.js}

@@ -9,11 +9,11 @@ const tryImport = async (result, name) => {
 };
 const getToJsonSchemaFn = async (vendor) => {
 	switch (vendor) {
-		case "arktype": return import("./arktype-C-GObzDh-CNoBqQrr.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
-		case "effect": return import("./effect-WSjEuzC9-DHMVzzyB.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
-		case "sury": return import("./sury-DmrZ3_Oj-Cpjsc2Lm.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
-		case "valibot": return import("./valibot-CQk-M5rL-BcaCeUrF.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
-		case "zod": return import("./zod-Db63SLXj-BIXn64AP.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
+		case "arktype": return import("./arktype-C-GObzDh-Bx7Fdrqj.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
+		case "effect": return import("./effect-WSjEuzC9-CZCpOgOT.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
+		case "sury": return import("./sury-DmrZ3_Oj-Lq7x0IZW.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
+		case "valibot": return import("./valibot-CQk-M5rL-btpzU8Qa.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
+		case "zod": return import("./zod-Db63SLXj-BqWqpKnQ.js").then(async ({ getToJsonSchemaFn: getToJsonSchemaFn2 }) => getToJsonSchemaFn2());
 		default: throw new Error(`xsschema: Unsupported schema vendor "${vendor}". see https://xsai.js.org/docs/packages-top/xsschema#unsupported-schema-vendor`);
 	}
 };