codex-usage-analyzer 0.1.0 → 0.2.0

package/src/cli.js

@@ -1,75 +1,88 @@
-import {
-  analyzeUsage,
-  createSampleUsageSnapshotV2
-} from "./analyze.js";
+import { readAccountUsage } from "./account-usage.js";
+import { CodexUsageError } from "./errors.js";
+import { formatAccountUsage } from "./format-account-usage.js";
+
+export const PACKAGE_NAME = "codex-usage-analyzer";
+export const PACKAGE_VERSION = "0.2.0";
 
 const USAGE = [
+  "codex-usage-analyzer - Read your Codex account usage",
+  "",
   "Usage:",
-  "  codex-usage-analyzer analyze --json [--codex-home <path>]",
-  "  codex-usage-analyzer analyze --json --fixture-sample"
+  "  codex-usage-analyzer [usage] [--json]",
+  "  codex-usage-analyzer [usage] --help",
+  "  codex-usage-analyzer --version"
 ].join("\n");
 
-export async function runCli(argv, io = {}) {
+export async function runCli(argv, io = {}, dependencies = {}) {
   const stdout = io.stdout ?? process.stdout;
   const stderr = io.stderr ?? process.stderr;
+  const parsed = parseArguments(argv);
 
-  if (argv.includes("--help") || argv.includes("-h")) {
+  if (parsed.action === "help") {
     stdout.write(`${USAGE}\n`);
     return 0;
   }
 
-  const [command, ...flags] = argv;
-
-  if (command !== "analyze") {
-    stderr.write(`${USAGE}\n`);
-    return 1;
+  if (parsed.action === "version") {
+    stdout.write(`${PACKAGE_VERSION}\n`);
+    return 0;
   }
 
-  const parsedFlags = parseAnalyzeFlags(flags);
-  if (!parsedFlags.ok) {
+  if (parsed.action === "invalid") {
     stderr.write(`${USAGE}\n`);
     return 1;
   }
 
-  const snapshot = parsedFlags.fixtureSample
-    ? createSampleUsageSnapshotV2()
-    : await analyzeUsage({
-      codexHome: parsedFlags.codexHome
-    });
-  stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
-  return 0;
-}
+  const readUsage = dependencies.readAccountUsage ?? readAccountUsage;
+  const formatUsage = dependencies.formatAccountUsage ?? formatAccountUsage;
 
-function parseAnalyzeFlags(flags) {
-  const parsed = {
-    codexHome: null,
-    fixtureSample: false,
-    hasJson: false,
-    ok: true
-  };
-
-  for (let index = 0; index < flags.length; index += 1) {
-    const flag = flags[index];
-
-    if (flag === "--json") {
-      parsed.hasJson = true;
-    } else if (flag === "--fixture-sample") {
-      parsed.fixtureSample = true;
-    } else if (flag === "--codex-home") {
-      const value = flags[index + 1];
-      if (value === undefined || value.startsWith("--")) {
-        return { ok: false };
-      }
-
-      parsed.codexHome = value;
-      index += 1;
+  try {
+    const usage = await readUsage();
+    const output = parsed.json
+      ? JSON.stringify(usage, null, 2)
+      : formatUsage(usage);
+    stdout.write(`${output}\n`);
+    return 0;
+  } catch (error) {
+    if (error instanceof CodexUsageError) {
+      stderr.write(`${PACKAGE_NAME}: ${error.message} [${error.code}]\n`);
     } else {
-      return { ok: false };
+      stderr.write(`${PACKAGE_NAME}: Unexpected failure. [UNEXPECTED_ERROR]\n`);
     }
+
+    return 1;
+  }
+}
+
+function parseArguments(argv) {
+  const args = [...argv];
+
+  if (args[0] === "usage") {
+    args.shift();
+  } else if (args[0] !== undefined && !args[0].startsWith("-")) {
+    return { action: "invalid" };
+  }
+
+  if (args.length === 0) {
+    return { action: "usage", json: false };
+  }
+
+  if (args.length !== 1) {
+    return { action: "invalid" };
+  }
+
+  if (args[0] === "--json") {
+    return { action: "usage", json: true };
+  }
+
+  if (args[0] === "--help" || args[0] === "-h") {
+    return { action: "help" };
+  }
+
+  if (args[0] === "--version" || args[0] === "-v") {
+    return { action: "version" };
   }
 
-  return {
-    ...parsed,
-    ok: parsed.hasJson
-  };
+  return { action: "invalid" };
 }

package/src/errors.js

@@ -0,0 +1,46 @@
+export const CODEX_USAGE_ERROR_CODES = Object.freeze({
+  INVALID_TIMEOUT: "INVALID_TIMEOUT",
+  CODEX_NOT_FOUND: "CODEX_NOT_FOUND",
+  APP_SERVER_START_FAILED: "APP_SERVER_START_FAILED",
+  APP_SERVER_EXITED: "APP_SERVER_EXITED",
+  APP_SERVER_TIMEOUT: "APP_SERVER_TIMEOUT",
+  APP_SERVER_PROTOCOL_ERROR: "APP_SERVER_PROTOCOL_ERROR",
+  APP_SERVER_RPC_ERROR: "APP_SERVER_RPC_ERROR",
+  INVALID_ACCOUNT_USAGE_RESPONSE: "INVALID_ACCOUNT_USAGE_RESPONSE"
+});
+
+const ERROR_MESSAGES = Object.freeze({
+  [CODEX_USAGE_ERROR_CODES.INVALID_TIMEOUT]:
+    "timeoutMs must be an integer between 1 and 120000.",
+  [CODEX_USAGE_ERROR_CODES.CODEX_NOT_FOUND]:
+    "Codex CLI was not found. Install or update Codex, then sign in with ChatGPT.",
+  [CODEX_USAGE_ERROR_CODES.APP_SERVER_START_FAILED]:
+    "Codex app-server could not be started.",
+  [CODEX_USAGE_ERROR_CODES.APP_SERVER_EXITED]:
+    "Codex app-server exited before returning account usage.",
+  [CODEX_USAGE_ERROR_CODES.APP_SERVER_TIMEOUT]:
+    "Codex app-server timed out before returning account usage.",
+  [CODEX_USAGE_ERROR_CODES.APP_SERVER_PROTOCOL_ERROR]:
+    "Codex app-server returned an invalid protocol message.",
+  [CODEX_USAGE_ERROR_CODES.APP_SERVER_RPC_ERROR]:
+    "Codex app-server could not read account usage. Check your Codex version and ChatGPT sign-in.",
+  [CODEX_USAGE_ERROR_CODES.INVALID_ACCOUNT_USAGE_RESPONSE]:
+    "Codex app-server returned an invalid account usage response."
+});
+
+export class CodexUsageError extends Error {
+  constructor(code, options = {}) {
+    const message = ERROR_MESSAGES[code];
+    if (message === undefined) {
+      throw new TypeError("Unknown Codex usage error code");
+    }
+
+    super(message);
+    this.name = "CodexUsageError";
+    this.code = code;
+
+    if (Number.isInteger(options.rpcCode)) {
+      this.rpcCode = options.rpcCode;
+    }
+  }
+}

package/src/format-account-usage.js

@@ -0,0 +1,81 @@
+const UNAVAILABLE = "Unavailable";
+
+export function formatAccountUsage(usage) {
+  const rows = [
+    ["Lifetime tokens", formatCompactInteger(usage.summary.lifetimeTokens)],
+    ["Peak daily tokens", formatCompactInteger(usage.summary.peakDailyTokens)],
+    ["Longest turn", formatDuration(usage.summary.longestRunningTurnSec)],
+    ["Current streak", formatDays(usage.summary.currentStreakDays)],
+    ["Longest streak", formatDays(usage.summary.longestStreakDays)],
+    ["Daily buckets", formatBucketCount(usage.dailyUsageBuckets)]
+  ];
+  const labelWidth = Math.max(...rows.map(([label]) => label.length));
+
+  return [
+    "Codex account usage",
+    "",
+    ...rows.map(([label, value]) => `${label.padEnd(labelWidth)}  ${value}`),
+    "",
+    `Captured at ${usage.capturedAt}`
+  ].join("\n");
+}
+
+function formatCompactInteger(value) {
+  if (value === null) return UNAVAILABLE;
+
+  const units = [
+    [1_000_000_000_000, "T"],
+    [1_000_000_000, "B"],
+    [1_000_000, "M"],
+    [1_000, "K"]
+  ];
+
+  for (const [divisor, suffix] of units) {
+    if (value >= divisor) {
+      const scaled = value / divisor;
+      return `${trimTrailingZeros(scaled.toFixed(2))}${suffix}`;
+    }
+  }
+
+  return String(value);
+}
+
+function formatDuration(value) {
+  if (value === null) return UNAVAILABLE;
+  if (value === 0) return "0s";
+
+  let remaining = value;
+  const units = [
+    [86_400, "d"],
+    [3_600, "h"],
+    [60, "m"],
+    [1, "s"]
+  ];
+  const parts = [];
+
+  for (const [seconds, suffix] of units) {
+    const amount = Math.floor(remaining / seconds);
+    if (amount > 0) {
+      parts.push(`${amount}${suffix}`);
+      remaining -= amount * seconds;
+    }
+
+    if (parts.length === 2) break;
+  }
+
+  return parts.join(" ");
+}
+
+function formatDays(value) {
+  if (value === null) return UNAVAILABLE;
+  return `${value} ${value === 1 ? "day" : "days"}`;
+}
+
+function formatBucketCount(value) {
+  if (value === null) return UNAVAILABLE;
+  return `${value.length} ${value.length === 1 ? "day" : "days"}`;
+}
+
+function trimTrailingZeros(value) {
+  return value.replace(/\.0+$/u, "").replace(/(\.\d*?)0+$/u, "$1");
+}

package/src/index.d.ts

@@ -1,23 +1,63 @@
-import type { UsageSnapshotV2 } from "./snapshot/v2-types.js";
-
-export * from "./snapshot/v2-types.js";
-
-export declare const ANALYZER_NAME: "codex-usage-analyzer";
-export declare const ANALYZER_VERSION: string;
-
-export interface AnalyzeUsageOptions {
-  /**
-   * Capture timestamp for the production snapshot. Defaults to the analyzer run time.
-   */
-  capturedAt?: string | Date | null;
-  /**
-   * Local Codex home root for parser source discovery.
-   */
-  codexHome?: string | null;
-  /**
-   * Deterministic clock value for date and streak calculations in parser tests.
-   */
-  now?: string | Date | null;
+export declare const PACKAGE_NAME: "codex-usage-analyzer";
+export declare const PACKAGE_VERSION: "0.2.0";
+export declare const ACCOUNT_USAGE_CONTRACT_VERSION: 1;
+export declare const ACCOUNT_USAGE_SUMMARY_FIELDS: readonly [
+  "lifetimeTokens",
+  "peakDailyTokens",
+  "longestRunningTurnSec",
+  "currentStreakDays",
+  "longestStreakDays"
+];
+
+export interface AccountUsageSummary {
+  lifetimeTokens: number | null;
+  peakDailyTokens: number | null;
+  longestRunningTurnSec: number | null;
+  currentStreakDays: number | null;
+  longestStreakDays: number | null;
+}
+
+export interface AccountUsageDailyBucket {
+  startDate: string;
+  tokens: number;
+}
+
+export interface AccountUsageDocument {
+  contractVersion: 1;
+  capturedAt: string;
+  summary: AccountUsageSummary;
+  dailyUsageBuckets: AccountUsageDailyBucket[] | null;
+}
+
+export interface ReadAccountUsageOptions {
+  timeoutMs?: number;
+}
+
+export type CodexUsageErrorCode =
+  | "INVALID_TIMEOUT"
+  | "CODEX_NOT_FOUND"
+  | "APP_SERVER_START_FAILED"
+  | "APP_SERVER_EXITED"
+  | "APP_SERVER_TIMEOUT"
+  | "APP_SERVER_PROTOCOL_ERROR"
+  | "APP_SERVER_RPC_ERROR"
+  | "INVALID_ACCOUNT_USAGE_RESPONSE";
+
+export declare const CODEX_USAGE_ERROR_CODES: Readonly<{
+  INVALID_TIMEOUT: "INVALID_TIMEOUT";
+  CODEX_NOT_FOUND: "CODEX_NOT_FOUND";
+  APP_SERVER_START_FAILED: "APP_SERVER_START_FAILED";
+  APP_SERVER_EXITED: "APP_SERVER_EXITED";
+  APP_SERVER_TIMEOUT: "APP_SERVER_TIMEOUT";
+  APP_SERVER_PROTOCOL_ERROR: "APP_SERVER_PROTOCOL_ERROR";
+  APP_SERVER_RPC_ERROR: "APP_SERVER_RPC_ERROR";
+  INVALID_ACCOUNT_USAGE_RESPONSE: "INVALID_ACCOUNT_USAGE_RESPONSE";
+}>;
+
+export declare class CodexUsageError extends Error {
+  readonly code: CodexUsageErrorCode;
+  readonly rpcCode?: number;
+  constructor(code: CodexUsageErrorCode, options?: { rpcCode?: number });
 }
 
 export interface CliIo {
@@ -29,18 +69,8 @@ export interface CliIo {
   };
 }
 
-/**
- * Analyze usage into a production UsageSnapshot v2.
- *
- * Local session JSONL sources, including allowlisted usage and skill/plugin
- * invocation events, are parsed when available. Unavailable fields are
- * represented with zero/null/empty values plus a namespaced diagnostic
- * extension. This function does not return the sample fixture.
- */
-export declare function analyzeUsage(options?: AnalyzeUsageOptions): Promise<UsageSnapshotV2>;
-
-export declare function createSampleUsageSnapshotV2(
-  overrides?: Record<string, unknown>
-): UsageSnapshotV2;
+export declare function readAccountUsage(
+  options?: ReadAccountUsageOptions
+): Promise<AccountUsageDocument>;
 
 export declare function runCli(argv: string[], io?: CliIo): Promise<number>;

package/src/index.js

@@ -1,17 +1,13 @@
 export {
-  ANALYZER_NAME,
-  ANALYZER_VERSION,
-  analyzeUsage,
-  createSampleUsageSnapshotV2
-} from "./analyze.js";
+  ACCOUNT_USAGE_CONTRACT_VERSION,
+  ACCOUNT_USAGE_SUMMARY_FIELDS,
+  readAccountUsage
+} from "./account-usage.js";
 
-export {
-  USAGE_SNAPSHOT_V2_SCHEMA_VERSION,
-  assertUsageSnapshotV2,
-  isUsageSnapshotV2,
-  validateUsageSnapshotV2
-} from "./snapshot/v2-schema.js";
-
-export { sampleUsageSnapshotV2 } from "./fixtures/sample-v2-snapshot.js";
+export { CODEX_USAGE_ERROR_CODES, CodexUsageError } from "./errors.js";
 
-export { runCli } from "./cli.js";
+export {
+  PACKAGE_NAME,
+  PACKAGE_VERSION,
+  runCli
+} from "./cli.js";

package/src/analyze.js

@@ -1,239 +0,0 @@
-import { sampleUsageSnapshotV2 } from "./fixtures/sample-v2-snapshot.js";
-import { aggregateActivityFromCodexHome } from "./parser/activity-aggregate.js";
-import { aggregateCodexAssetsFromCodexHome } from "./parser/asset-aggregate.js";
-import { aggregateModelUsageFromCodexHome } from "./parser/model-aggregate.js";
-import { aggregateSkillPluginUsageFromCodexHome } from "./parser/skill-plugin-aggregate.js";
-import { aggregateTokenUsageFromCodexHome } from "./parser/token-aggregate.js";
-import {
-  USAGE_SNAPSHOT_V2_SCHEMA_VERSION,
-  assertUsageSnapshotV2
-} from "./snapshot/v2-schema.js";
-
-export const ANALYZER_NAME = "codex-usage-analyzer";
-export const ANALYZER_VERSION = "0.1.0";
-
-export async function analyzeUsage(options = {}) {
-  const [
-    usageAggregate,
-    modelAggregate,
-    activityAggregate,
-    skillPluginAggregate,
-    assetAggregate
-  ] = await Promise.all([
-    aggregateTokenUsageFromCodexHome(options),
-    aggregateModelUsageFromCodexHome(options),
-    aggregateActivityFromCodexHome(options),
-    aggregateSkillPluginUsageFromCodexHome(options),
-    aggregateCodexAssetsFromCodexHome(options)
-  ]);
-
-  const snapshot = createUnavailableUsageSnapshotV2({
-    capturedAt: normalizeCapturedAt(options.capturedAt),
-    producer: {
-      name: ANALYZER_NAME,
-      version: ANALYZER_VERSION
-    }
-  });
-
-  if (usageAggregate.diagnostics.status === "ok") {
-    snapshot.usage = usageAggregate.usage;
-  }
-
-  if (modelAggregate.diagnostics.status === "ok") {
-    snapshot.models = modelAggregate.models;
-  }
-
-  if (activityAggregate.diagnostics.status === "ok") {
-    snapshot.activity = activityAggregate.activity;
-  }
-
-  if (skillPluginAggregate.diagnostics.status === "ok") {
-    snapshot.skills = skillPluginAggregate.skills;
-    snapshot.plugins = skillPluginAggregate.plugins;
-  }
-
-  if (assetAggregate.diagnostics.status === "ok") {
-    snapshot.codexAssets = assetAggregate.codexAssets;
-  }
-
-  snapshot.extensions["codexUsageAnalyzer.diagnostics"] = createAnalyzerDiagnostics({
-    activity: activityAggregate,
-    assets: assetAggregate,
-    models: modelAggregate,
-    skillPlugin: skillPluginAggregate,
-    usage: usageAggregate
-  });
-
-  return assertUsageSnapshotV2(snapshot);
-}
-
-function createUnavailableUsageSnapshotV2(overrides = {}) {
-  return mergeSnapshot({
-    schemaVersion: USAGE_SNAPSHOT_V2_SCHEMA_VERSION,
-    capturedAt: new Date().toISOString(),
-    producer: {
-      name: ANALYZER_NAME,
-      version: ANALYZER_VERSION
-    },
-    usage: {
-      totalTokens: 0,
-      peakDailyTokens: null,
-      tokenBreakdown: createUnavailableTokenBreakdown(),
-      daily: []
-    },
-    models: {
-      favoriteModel: null,
-      items: []
-    },
-    activity: {
-      longestTaskDurationMs: null,
-      currentStreakDays: null,
-      longestStreakDays: null,
-      fastModePercent: null,
-      reasoningEffort: null,
-      reasoningEffortPercent: null,
-      totalThreads: null
-    },
-    skills: {
-      exploredCount: null,
-      totalUsed: null,
-      topSkills: []
-    },
-    plugins: {
-      topPlugins: []
-    },
-    extensions: {
-      "codexUsageAnalyzer.diagnostics": {
-        status: "unavailable",
-        reason: "local_sources_unavailable",
-        unavailableFields: ["usage", "models", "activity", "skills", "plugins"]
-      }
-    }
-  }, overrides);
-}
-
-function createUnavailableTokenBreakdown() {
-  return {
-    inputTokens: null,
-    outputTokens: null,
-    cacheReadTokens: null,
-    cacheWriteTokens: null,
-    reasoningTokens: null
-  };
-}
-
-function createAnalyzerDiagnostics(aggregates) {
-  const skillPluginDiagnostics = aggregates.skillPlugin.diagnostics;
-  const diagnostics = {
-    usage: aggregates.usage.diagnostics,
-    models: aggregates.models.diagnostics,
-    activity: aggregates.activity.diagnostics,
-    skills: skillPluginDiagnostics,
-    plugins: skillPluginDiagnostics,
-    codexAssets: aggregates.assets.diagnostics
-  };
-
-  const parsedFields = [];
-  const unavailableFields = [];
-
-  for (const field of ["usage", "models", "activity"]) {
-    if (diagnostics[field].status === "ok") {
-      parsedFields.push(field);
-    } else {
-      unavailableFields.push(field);
-    }
-  }
-
-  if (skillPluginDiagnostics.status === "ok") {
-    parsedFields.push("skills", "plugins");
-  } else {
-    unavailableFields.push("skills", "plugins");
-  }
-
-  if (diagnostics.codexAssets.status === "ok") {
-    parsedFields.push("codexAssets");
-  } else {
-    unavailableFields.push("codexAssets");
-  }
-
-  if (diagnostics.activity.status === "ok") {
-    for (const field of diagnostics.activity.unavailableFields ?? []) {
-      unavailableFields.push(`activity.${field}`);
-    }
-  }
-
-  const status = parsedFields.length === 0
-    ? "unavailable"
-    : unavailableFields.length > 0
-      ? "partial"
-      : "ok";
-
-  return {
-    status,
-    reason: getAnalyzerDiagnosticReason(status, diagnostics),
-    parser: "session_jsonl",
-    source: diagnostics.usage.source,
-    profileComparison: {
-      status: "not_performed",
-      reason: "remote_profile_api_not_used",
-      localStreakBasis: "session_jsonl_utc_dates",
-      remoteProfileBasis: "codex_desktop_remote_profile_api",
-      parity: "not_guaranteed"
-    },
-    parsedFields,
-    unavailableFields,
-    ...diagnostics
-  };
-}
-
-function getAnalyzerDiagnosticReason(status, diagnostics) {
-  if (status === "ok") {
-    return null;
-  }
-
-  if (status === "partial") {
-    return "local_sources_partially_available";
-  }
-
-  return diagnostics.usage.reason
-    ?? diagnostics.models.reason
-    ?? diagnostics.activity.reason
-    ?? diagnostics.skills.reason
-    ?? diagnostics.plugins.reason
-    ?? diagnostics.codexAssets.reason
-    ?? "local_sources_unavailable";
-}
-
-export function createSampleUsageSnapshotV2(overrides = {}) {
-  return mergeSnapshot(structuredClone(sampleUsageSnapshotV2), overrides);
-}
-
-function normalizeCapturedAt(value) {
-  if (value === undefined || value === null) {
-    return new Date().toISOString();
-  }
-
-  const date = value instanceof Date ? value : new Date(value);
-
-  if (Number.isNaN(date.getTime())) {
-    throw new TypeError("capturedAt must be a valid date");
-  }
-
-  return date.toISOString();
-}
-
-function mergeSnapshot(target, source) {
-  for (const [key, value] of Object.entries(source)) {
-    if (isPlainObject(value) && isPlainObject(target[key])) {
-      target[key] = mergeSnapshot(target[key], value);
-    } else {
-      target[key] = value;
-    }
-  }
-
-  return target;
-}
-
-function isPlainObject(value) {
-  return value !== null && typeof value === "object" && !Array.isArray(value);
-}