ccusage 0.3.2 → 0.4.0

package/README.md

@@ -46,6 +46,16 @@ This tool helps you understand the value you're getting from your subscription b
 - 💰 **Cost Tracking**: Shows costs in USD for each day/session
 - 🔄 **Cache Token Support**: Tracks and displays cache creation and cache read tokens separately
 
+## Important Disclaimer
+
+⚠️ **This is NOT an official Claude tool** - it's an independent community project that analyzes locally stored usage data.
+
+**Cost calculations are estimates only** and may not reflect actual billing:
+- Costs shown are virtual/estimated based on token counts and model pricing data
+- Actual costs may vary due to pricing changes, special rates, or billing adjustments
+- We do not guarantee the accuracy of calculated costs
+- For official billing information, always refer to your Claude account dashboard
+
 ## Limitations
 
 - This tool only reads local JSONL files generated by Claude Code. If you use Claude Code with multiple devices, you need to ensure the JSONL files are synchronized across devices.
@@ -113,6 +123,11 @@ ccusage daily --path /custom/path/to/.claude
 
 # Output in JSON format
 ccusage daily --json
+
+# Control cost calculation mode
+ccusage daily --mode auto       # Use costUSD when available, calculate otherwise (default)
+ccusage daily --mode calculate  # Always calculate costs from tokens
+ccusage daily --mode display    # Always show pre-calculated costUSD values
 ```
 
 `ccusage` is an alias for `ccusage daily`, so you can run it without specifying the subcommand.
@@ -133,6 +148,11 @@ ccusage session --since 20250525 --until 20250530 --path /custom/path
 
 # Output in JSON format
 ccusage session --json
+
+# Control cost calculation mode
+ccusage session --mode auto       # Use costUSD when available, calculate otherwise (default)
+ccusage session --mode calculate  # Always calculate costs from tokens
+ccusage session --mode display    # Always show pre-calculated costUSD values
 ```
 
 ### Options
@@ -143,9 +163,18 @@ All commands support the following options:
 - `-u, --until <date>`: Filter until date (YYYYMMDD format)  
 - `-p, --path <path>`: Custom path to Claude data directory (default: `~/.claude`)
 - `-j, --json`: Output results in JSON format instead of table
+- `-m, --mode <mode>`: Cost calculation mode: `auto` (default), `calculate`, or `display`
+- `-d, --debug`: Show pricing mismatch information for debugging
+- `--debug-samples <number>`: Number of sample discrepancies to show in debug output (default: 5)
 - `-h, --help`: Display help message
 - `-v, --version`: Display version
 
+#### Cost Calculation Modes
+
+- **`auto`** (default): Uses pre-calculated `costUSD` values when available, falls back to calculating costs from token counts using model pricing
+- **`calculate`**: Always calculates costs from token counts using model pricing, ignores any pre-calculated `costUSD` values
+- **`display`**: Always uses pre-calculated `costUSD` values only, shows $0.00 for entries without pre-calculated costs
+
 ## Output Example
 
 ### Daily Report

package/dist/calculate-cost.d.ts

@@ -1,21 +1,5 @@
-import { DailyUsage, SessionUsage } from "./data-loader-ToqWI8hT.js";
+import { DailyUsage, SessionUsage, TokenData, TokenTotals } from "./data-loader-D1LHcGfa.js";
 
-//#region types.d.ts
-
-interface TokenTotals {
-  inputTokens: number;
-  outputTokens: number;
-  cacheCreationTokens: number;
-  cacheReadTokens: number;
-  totalCost: number;
-}
-interface TokenData {
-  inputTokens: number;
-  outputTokens: number;
-  cacheCreationTokens: number;
-  cacheReadTokens: number;
-}
-//#endregion
 //#region calculate-cost.d.ts
 declare function calculateTotals(data: Array<DailyUsage | SessionUsage>): TokenTotals;
 declare function getTotalTokens(tokens: TokenData): number;

package/dist/{data-loader-ToqWI8hT.d.ts → data-loader-D1LHcGfa.d.ts}

@@ -929,6 +929,71 @@ type PipeItemAsync<TInput, TOutput, TIssue extends BaseIssue<unknown>> = BaseSch
  * Schema without pipe type.
  */
 
+/**
+ * Array issue interface.
+ */
+interface ArrayIssue extends BaseIssue<unknown> {
+  /**
+   * The issue kind.
+   */
+  readonly kind: 'schema';
+  /**
+   * The issue type.
+   */
+  readonly type: 'array';
+  /**
+   * The expected property.
+   */
+  readonly expected: 'Array';
+}
+
+/**
+ * Array schema interface.
+ */
+interface ArraySchema<TItem extends BaseSchema<unknown, unknown, BaseIssue<unknown>>, TMessage extends ErrorMessage<ArrayIssue> | undefined> extends BaseSchema<InferInput<TItem>[], InferOutput<TItem>[], ArrayIssue | InferIssue<TItem>> {
+  /**
+   * The schema type.
+   */
+  readonly type: 'array';
+  /**
+   * The schema reference.
+   */
+  readonly reference: typeof array;
+  /**
+   * The expected property.
+   */
+  readonly expects: 'Array';
+  /**
+   * The array item schema.
+   */
+  readonly item: TItem;
+  /**
+   * The error message.
+   */
+  readonly message: TMessage;
+}
+/**
+ * Creates an array schema.
+ *
+ * @param item The item schema.
+ *
+ * @returns An array schema.
+ */
+declare function array<const TItem extends BaseSchema<unknown, unknown, BaseIssue<unknown>>>(item: TItem): ArraySchema<TItem, undefined>;
+/**
+ * Creates an array schema.
+ *
+ * @param item The item schema.
+ * @param message The error message.
+ *
+ * @returns An array schema.
+ */
+declare function array<const TItem extends BaseSchema<unknown, unknown, BaseIssue<unknown>>, const TMessage extends ErrorMessage<ArrayIssue> | undefined>(item: TItem, message: TMessage): ArraySchema<TItem, TMessage>;
+
+/**
+ * Array schema interface.
+ */
+
 /**
  * Exact optional schema interface.
  */
@@ -1418,10 +1483,37 @@ declare function readonly<TInput>(): ReadonlyAction<TInput>;
  * Array action type.
  */
 //#endregion
+//#region pricing-fetcher.d.ts
+declare const ModelPricingSchema: ObjectSchema<{
+  readonly input_cost_per_token: OptionalSchema<NumberSchema<undefined>, undefined>;
+  readonly output_cost_per_token: OptionalSchema<NumberSchema<undefined>, undefined>;
+  readonly cache_creation_input_token_cost: OptionalSchema<NumberSchema<undefined>, undefined>;
+  readonly cache_read_input_token_cost: OptionalSchema<NumberSchema<undefined>, undefined>;
+}, undefined>;
+type ModelPricing = InferOutput<typeof ModelPricingSchema>;
+//#endregion
+//#region types.d.ts
+interface TokenTotals {
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationTokens: number;
+  cacheReadTokens: number;
+  totalCost: number;
+}
+interface TokenData {
+  inputTokens: number;
+  outputTokens: number;
+  cacheCreationTokens: number;
+  cacheReadTokens: number;
+}
+declare const CostModes: readonly ["auto", "calculate", "display"];
+type CostMode = (typeof CostModes)[number];
+//#endregion
 //#region data-loader.d.ts
 declare const getDefaultClaudePath: () => string;
 declare const UsageDataSchema: ObjectSchema<{
   readonly timestamp: StringSchema<undefined>;
+  readonly version: OptionalSchema<StringSchema<undefined>, undefined>;
   readonly message: ObjectSchema<{
     readonly usage: ObjectSchema<{
       readonly input_tokens: NumberSchema<undefined>;
@@ -1429,8 +1521,9 @@ declare const UsageDataSchema: ObjectSchema<{
       readonly cache_creation_input_tokens: OptionalSchema<NumberSchema<undefined>, undefined>;
       readonly cache_read_input_tokens: OptionalSchema<NumberSchema<undefined>, undefined>;
     }, undefined>;
+    readonly model: OptionalSchema<StringSchema<undefined>, undefined>;
   }, undefined>;
-  readonly costUSD: NumberSchema<undefined>;
+  readonly costUSD: OptionalSchema<NumberSchema<undefined>, undefined>;
 }, undefined>;
 type UsageData = InferOutput<typeof UsageDataSchema>;
 declare const DailyUsageSchema: ObjectSchema<{
@@ -1451,17 +1544,20 @@ declare const SessionUsageSchema: ObjectSchema<{
   readonly cacheReadTokens: NumberSchema<undefined>;
   readonly totalCost: NumberSchema<undefined>;
   readonly lastActivity: StringSchema<undefined>;
+  readonly versions: ArraySchema<StringSchema<undefined>, undefined>;
 }, undefined>;
 type SessionUsage = InferOutput<typeof SessionUsageSchema>;
 declare const formatDate: (dateStr: string) => string;
+declare const calculateCostForEntry: (data: UsageData, mode: CostMode, modelPricing: Record<string, ModelPricing>) => number;
 interface DateFilter {
   since?: string;
   until?: string;
 }
 interface LoadOptions extends DateFilter {
   claudePath?: string;
+  mode?: CostMode;
 }
 declare function loadUsageData(options?: LoadOptions): Promise<DailyUsage[]>;
 declare function loadSessionData(options?: LoadOptions): Promise<SessionUsage[]>;
 //#endregion
-export { DailyUsage, DailyUsageSchema as DailyUsageSchema$1, DateFilter, LoadOptions, SessionUsage, SessionUsageSchema as SessionUsageSchema$1, UsageData, UsageDataSchema as UsageDataSchema$1, formatDate as formatDate$1, getDefaultClaudePath as getDefaultClaudePath$1, loadSessionData as loadSessionData$1, loadUsageData as loadUsageData$1 };
+export { DailyUsage, DailyUsageSchema as DailyUsageSchema$1, DateFilter, LoadOptions, SessionUsage, SessionUsageSchema as SessionUsageSchema$1, TokenData, TokenTotals, UsageData, UsageDataSchema as UsageDataSchema$1, calculateCostForEntry as calculateCostForEntry$1, formatDate as formatDate$1, getDefaultClaudePath as getDefaultClaudePath$1, loadSessionData as loadSessionData$1, loadUsageData as loadUsageData$1 };