axusage 2.0.0

package/dist/types/chatgpt.js

@@ -0,0 +1,21 @@
+import { z } from "zod";
+/**
+ * ChatGPT API response schemas
+ */
+export const ChatGPTRateLimitWindow = z.object({
+    used_percent: z.number(),
+    limit_window_seconds: z.number(),
+    reset_after_seconds: z.number(),
+    reset_at: z.number(), // Unix timestamp
+});
+const ChatGPTRateLimit = z.object({
+    allowed: z.boolean(),
+    limit_reached: z.boolean(),
+    primary_window: ChatGPTRateLimitWindow,
+    secondary_window: ChatGPTRateLimitWindow,
+});
+export const ChatGPTUsageResponse = z.object({
+    plan_type: z.string(),
+    rate_limit: ChatGPTRateLimit,
+    credits: z.unknown().nullable(),
+});

package/dist/types/domain.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Common domain types for representing usage data across different services
+ */
+/**
+ * A single usage window/period with utilization data
+ */
+export type UsageWindow = {
+    readonly name: string;
+    readonly utilization: number;
+    readonly resetsAt: Date | undefined;
+    readonly periodDurationMs: number;
+};
+/**
+ * Complete usage data for a service
+ */
+export type ServiceUsageData = {
+    readonly service: string;
+    readonly planType?: string;
+    readonly windows: readonly UsageWindow[];
+    readonly metadata?: {
+        readonly allowed?: boolean;
+        readonly limitReached?: boolean;
+    };
+};
+/**
+ * Result type for API operations
+ */
+export type Result<T, E extends Error> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+/**
+ * Base error class for API errors
+ */
+export declare class ApiError extends Error {
+    readonly status?: number;
+    readonly body?: unknown;
+    constructor(message: string, status?: number, body?: unknown);
+}
+/**
+ * Service adapter interface
+ */
+export interface ServiceAdapter {
+    readonly name: string;
+    fetchUsage(): Promise<Result<ServiceUsageData, ApiError>>;
+}
+/**
+ * Result of fetching usage for a single service.
+ * Wraps the service name with its usage data result or error.
+ */
+export type ServiceResult = {
+    readonly service: string;
+    readonly result: Result<ServiceUsageData, ApiError>;
+};

package/dist/types/domain.js

@@ -0,0 +1,16 @@
+/**
+ * Common domain types for representing usage data across different services
+ */
+/**
+ * Base error class for API errors
+ */
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = "ApiError";
+        this.status = status;
+        this.body = body;
+    }
+}

package/dist/types/gemini.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/**
+ * Quota API bucket schema
+ */
+export declare const GeminiQuotaBucket: z.ZodObject<{
+    modelId: z.ZodString;
+    remainingFraction: z.ZodNumber;
+    resetTime: z.ZodOptional<z.ZodString>;
+    tokenType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type GeminiQuotaBucket = z.infer<typeof GeminiQuotaBucket>;
+/**
+ * Quota API response schema
+ */
+export declare const GeminiQuotaResponse: z.ZodObject<{
+    buckets: z.ZodArray<z.ZodObject<{
+        modelId: z.ZodString;
+        remainingFraction: z.ZodNumber;
+        resetTime: z.ZodOptional<z.ZodString>;
+        tokenType: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GeminiQuotaResponse = z.infer<typeof GeminiQuotaResponse>;
+export declare const GeminiProjectsResponse: z.ZodObject<{
+    projects: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        projectId: z.ZodString;
+        projectNumber: z.ZodOptional<z.ZodString>;
+        labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type GeminiProjectsResponse = z.infer<typeof GeminiProjectsResponse>;

package/dist/types/gemini.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/**
+ * Quota API bucket schema
+ */
+export const GeminiQuotaBucket = z.object({
+    modelId: z.string(),
+    remainingFraction: z.number(), // 0-1
+    resetTime: z.string().optional(), // ISO8601
+    tokenType: z.string().optional(), // "input" | "output"
+});
+/**
+ * Quota API response schema
+ */
+export const GeminiQuotaResponse = z.object({
+    buckets: z.array(GeminiQuotaBucket),
+});
+/**
+ * Cloud Resource Manager projects response
+ */
+const GeminiProject = z.object({
+    projectId: z.string(),
+    projectNumber: z.string().optional(),
+    labels: z.record(z.string(), z.string()).optional(),
+});
+export const GeminiProjectsResponse = z.object({
+    projects: z.array(GeminiProject).optional(),
+});

package/dist/types/github-copilot.d.ts

@@ -0,0 +1,21 @@
+import { z } from "zod";
+export declare const GitHubCopilotUsageResponse: z.ZodObject<{
+    licenseType: z.ZodString;
+    quotas: z.ZodObject<{
+        limits: z.ZodObject<{
+            premiumInteractions: z.ZodNumber;
+        }, z.core.$strip>;
+        remaining: z.ZodObject<{
+            premiumInteractions: z.ZodNumber;
+            chatPercentage: z.ZodOptional<z.ZodNumber>;
+            premiumInteractionsPercentage: z.ZodNumber;
+        }, z.core.$strip>;
+        resetDate: z.ZodString;
+        overagesEnabled: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>;
+    plan: z.ZodString;
+    trial: z.ZodOptional<z.ZodObject<{
+        eligible: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type GitHubCopilotUsageResponse = z.infer<typeof GitHubCopilotUsageResponse>;

package/dist/types/github-copilot.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+/**
+ * GitHub Copilot API response schemas
+ */
+const GitHubCopilotQuotaLimits = z.object({
+    premiumInteractions: z.number(),
+});
+const GitHubCopilotQuotaRemaining = z.object({
+    premiumInteractions: z.number(),
+    chatPercentage: z.number().optional(),
+    premiumInteractionsPercentage: z.number(),
+});
+const GitHubCopilotQuotas = z.object({
+    limits: GitHubCopilotQuotaLimits,
+    remaining: GitHubCopilotQuotaRemaining,
+    resetDate: z.string(), // Format: "YYYY-MM-DD"
+    overagesEnabled: z.boolean().optional(),
+});
+const GitHubCopilotTrial = z.object({
+    eligible: z.boolean(),
+});
+export const GitHubCopilotUsageResponse = z.object({
+    licenseType: z.string(),
+    quotas: GitHubCopilotQuotas,
+    plan: z.string(),
+    trial: GitHubCopilotTrial.optional(),
+});

package/dist/types/usage.d.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+/**
+ * Complete usage response from the Anthropic API
+ *
+ * Note: `seven_day_opus` and `seven_day_sonnet` can be null depending on the
+ * user's plan. The API may return either, both, or neither.
+ */
+export declare const UsageResponse: z.ZodObject<{
+    five_hour: z.ZodObject<{
+        utilization: z.ZodNumber;
+        resets_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>, z.ZodTransform<string | undefined, string | null | undefined>>;
+    }, z.core.$strip>;
+    seven_day: z.ZodObject<{
+        utilization: z.ZodNumber;
+        resets_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>, z.ZodTransform<string | undefined, string | null | undefined>>;
+    }, z.core.$strip>;
+    seven_day_oauth_apps: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        utilization: z.ZodNumber;
+        resets_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>, z.ZodTransform<string | undefined, string | null | undefined>>;
+    }, z.core.$strip>>>;
+    seven_day_opus: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        utilization: z.ZodNumber;
+        resets_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>, z.ZodTransform<string | undefined, string | null | undefined>>;
+    }, z.core.$strip>>>;
+    seven_day_sonnet: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        utilization: z.ZodNumber;
+        resets_at: z.ZodPipe<z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>, z.ZodTransform<string | undefined, string | null | undefined>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type UsageResponse = z.infer<typeof UsageResponse>;
+export type UsageResponseInput = z.input<typeof UsageResponse>;

package/dist/types/usage.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+/**
+ * Usage metric with utilization percentage and reset timestamp
+ */
+const UsageMetric = z.object({
+    utilization: z.number(),
+    // Transform API null to undefined so the rest of the app only handles string | undefined.
+    resets_at: z.iso
+        .datetime({ offset: true })
+        .nullish()
+        .transform((value) => value === null ? undefined : value),
+});
+/**
+ * Complete usage response from the Anthropic API
+ *
+ * Note: `seven_day_opus` and `seven_day_sonnet` can be null depending on the
+ * user's plan. The API may return either, both, or neither.
+ */
+export const UsageResponse = z.object({
+    five_hour: UsageMetric,
+    seven_day: UsageMetric,
+    seven_day_oauth_apps: UsageMetric.nullable().optional(),
+    seven_day_opus: UsageMetric.nullable().optional(),
+    seven_day_sonnet: UsageMetric.nullable().optional(),
+});

package/dist/utils/calculate-usage-rate.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Calculates usage rate based on time elapsed vs usage consumed
+ * Rate = actual_usage / expected_usage
+ *
+ * Returns undefined if insufficient time has elapsed for accurate rate calculation.
+ * Rate is shown after either {@link MIN_ELAPSED_FRACTION} of the period OR
+ * {@link MIN_ELAPSED_TIME_MS} has passed (whichever comes first).
+ */
+export declare function calculateUsageRate(utilization: number, resetsAt: Date | undefined, periodDurationMs: number): number | undefined;

package/dist/utils/calculate-usage-rate.js

@@ -0,0 +1,31 @@
+/** Minimum fraction of period that must elapse before showing rate */
+const MIN_ELAPSED_FRACTION = 0.05; // 5%
+/** Minimum time that must elapse before showing rate (2 hours in ms) */
+const MIN_ELAPSED_TIME_MS = 2 * 60 * 60 * 1000;
+/**
+ * Calculates usage rate based on time elapsed vs usage consumed
+ * Rate = actual_usage / expected_usage
+ *
+ * Returns undefined if insufficient time has elapsed for accurate rate calculation.
+ * Rate is shown after either {@link MIN_ELAPSED_FRACTION} of the period OR
+ * {@link MIN_ELAPSED_TIME_MS} has passed (whichever comes first).
+ */
+export function calculateUsageRate(utilization, resetsAt, periodDurationMs) {
+    if (!resetsAt)
+        return undefined;
+    if (periodDurationMs <= 0)
+        return 0;
+    const now = Date.now();
+    const resetTime = resetsAt.getTime();
+    const periodStart = resetTime - periodDurationMs;
+    const elapsedTime = now - periodStart;
+    if (elapsedTime <= 0)
+        return undefined;
+    // Avoid inaccurate rates early in the period
+    // Show rate after 5% of period OR 2 hours elapsed (whichever first)
+    const minElapsedTime = Math.min(periodDurationMs * MIN_ELAPSED_FRACTION, MIN_ELAPSED_TIME_MS);
+    if (elapsedTime < minElapsedTime)
+        return undefined;
+    const elapsedPercentage = (elapsedTime / periodDurationMs) * 100;
+    return utilization / elapsedPercentage;
+}

package/dist/utils/classify-usage-rate.d.ts

@@ -0,0 +1,6 @@
+type UsageRateCategory = "green" | "yellow" | "red";
+/**
+ * Classifies a usage rate into a severity bucket
+ */
+export declare function classifyUsageRate(rate: number): UsageRateCategory;
+export {};

package/dist/utils/classify-usage-rate.js

@@ -0,0 +1,10 @@
+/**
+ * Classifies a usage rate into a severity bucket
+ */
+export function classifyUsageRate(rate) {
+    if (rate > 1.5)
+        return "red";
+    if (rate > 1)
+        return "yellow";
+    return "green";
+}

package/dist/utils/format-prometheus-metrics.d.ts

@@ -0,0 +1,6 @@
+import type { ServiceUsageData } from "../types/domain.js";
+/**
+ * Formats service usage data as Prometheus text exposition using prom-client.
+ * Emits a gauge `axusage_utilization_percent{service,window}` per window.
+ */
+export declare function formatPrometheusMetrics(data: readonly ServiceUsageData[]): Promise<string>;

package/dist/utils/format-prometheus-metrics.js

@@ -0,0 +1,20 @@
+import { Gauge, Registry } from "prom-client";
+/**
+ * Formats service usage data as Prometheus text exposition using prom-client.
+ * Emits a gauge `axusage_utilization_percent{service,window}` per window.
+ */
+export async function formatPrometheusMetrics(data) {
+    const registry = new Registry();
+    const gauge = new Gauge({
+        name: "axusage_utilization_percent",
+        help: "Current utilization percentage by service/window",
+        labelNames: ["service", "window"],
+        registers: [registry],
+    });
+    for (const entry of data) {
+        for (const w of entry.windows) {
+            gauge.set({ service: entry.service, window: w.name }, w.utilization);
+        }
+    }
+    return registry.metrics();
+}

package/dist/utils/format-service-usage.d.ts

@@ -0,0 +1,18 @@
+import type { ServiceUsageData } from "../types/domain.js";
+/**
+ * Formats complete service usage data for human-readable display
+ */
+export declare function formatServiceUsageData(data: ServiceUsageData): string;
+/**
+ * Converts service usage data to a plain JSON-serializable object
+ */
+export declare function toJsonObject(data: ServiceUsageData): unknown;
+/**
+ * Formats service usage data as JSON string
+ */
+export declare function formatServiceUsageDataAsJson(data: ServiceUsageData): string;
+/**
+ * Formats multiple services' usage data as TSV with header.
+ * One row per usage window, tab-delimited, UPPERCASE headers.
+ */
+export declare function formatServiceUsageAsTsv(data: ServiceUsageData[]): string;

package/dist/utils/format-service-usage.js

@@ -0,0 +1,120 @@
+import chalk from "chalk";
+import { calculateUsageRate } from "./calculate-usage-rate.js";
+import { classifyUsageRate } from "./classify-usage-rate.js";
+/**
+ * Formats a utilization value as a percentage string
+ */
+function formatUtilization(utilization) {
+    return `${utilization.toFixed(2)}%`;
+}
+/**
+ * Formats a Date as a human-readable date string
+ */
+function formatResetTime(date) {
+    return date ? date.toLocaleString() : "Not available";
+}
+/**
+ * Gets color for utilization based on usage rate
+ * Green: on track or under (rate ≤ 1.0)
+ * Yellow: slightly over budget (1.0 < rate ≤ 1.5)
+ * Red: significantly over budget (rate > 1.5)
+ */
+function getUtilizationColor(rate) {
+    if (rate === undefined)
+        return chalk.gray;
+    const bucket = classifyUsageRate(rate);
+    if (bucket === "red")
+        return chalk.red;
+    if (bucket === "yellow")
+        return chalk.yellow;
+    return chalk.green;
+}
+/**
+ * Formats a single usage window for display
+ */
+function formatUsageWindow(window) {
+    const utilizationString = formatUtilization(window.utilization);
+    const rate = calculateUsageRate(window.utilization, window.resetsAt, window.periodDurationMs);
+    const coloredUtilization = getUtilizationColor(rate)(utilizationString);
+    const resetTime = formatResetTime(window.resetsAt);
+    // Build full display string for rate to keep formatting consistent
+    const rateDisplay = rate === undefined ? "Not available" : `${rate.toFixed(2)}x rate`;
+    return `${chalk.bold(window.name)}:
+  Utilization: ${coloredUtilization} (${rateDisplay})
+  Resets at:   ${resetTime}`;
+}
+/**
+ * Formats complete service usage data for human-readable display
+ */
+export function formatServiceUsageData(data) {
+    const header = [
+        chalk.cyan.bold(`=== ${data.service} Usage ===`),
+        data.planType ? chalk.gray(`Plan: ${data.planType}`) : undefined,
+        data.metadata?.limitReached === true
+            ? chalk.red("⚠ Rate limit reached")
+            : data.metadata?.allowed === false
+                ? chalk.red("⚠ Usage not allowed")
+                : undefined,
+    ]
+        .filter(Boolean)
+        .join("\n");
+    const windows = data.windows
+        .map((window) => formatUsageWindow(window))
+        .join("\n\n");
+    return `${header}\n\n${windows}`;
+}
+/**
+ * Converts service usage data to a plain JSON-serializable object
+ */
+export function toJsonObject(data) {
+    return {
+        service: data.service,
+        planType: data.planType,
+        windows: data.windows.map((w) => ({
+            name: w.name,
+            utilization: w.utilization,
+            resetsAt: w.resetsAt?.toISOString(),
+            periodDurationMs: w.periodDurationMs,
+        })),
+        metadata: data.metadata,
+    };
+}
+/**
+ * Formats service usage data as JSON string
+ */
+export function formatServiceUsageDataAsJson(data) {
+    // eslint-disable-next-line unicorn/no-null -- JSON.stringify requires null for no replacer
+    return JSON.stringify(toJsonObject(data), null, 2);
+}
+const TSV_HEADER = "SERVICE\tPLAN\tWINDOW\tUTILIZATION\tRATE\tRESETS_AT";
+/**
+ * Sanitizes a string for TSV output by replacing tabs and newlines with spaces.
+ */
+function sanitizeForTsv(value) {
+    return value.replaceAll(/[\t\n\r]/gu, " ");
+}
+/**
+ * Formats a single service's usage data as TSV rows (no header).
+ * One row per usage window.
+ */
+function formatServiceUsageRowsAsTsv(data) {
+    return data.windows.map((w) => {
+        const rate = calculateUsageRate(w.utilization, w.resetsAt, w.periodDurationMs);
+        return [
+            sanitizeForTsv(data.service),
+            sanitizeForTsv(data.planType ?? "-"),
+            sanitizeForTsv(w.name),
+            w.utilization.toFixed(2),
+            rate?.toFixed(2) ?? "-",
+            w.resetsAt?.toISOString() ?? "-",
+        ].join("\t");
+    });
+}
+/**
+ * Formats multiple services' usage data as TSV with header.
+ * One row per usage window, tab-delimited, UPPERCASE headers.
+ */
+export function formatServiceUsageAsTsv(data) {
+    const rows = data.flatMap((d) => formatServiceUsageRowsAsTsv(d));
+    return [TSV_HEADER, ...rows].join("\n");
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "axusage",
+  "author": "Łukasz Jerciński",
+  "license": "MIT",
+  "version": "2.0.0",
+  "description": "Monitor API usage across Claude, ChatGPT, GitHub Copilot, and Gemini from a single CLI",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Jercik/axusage.git"
+  },
+  "type": "module",
+  "bin": {
+    "axusage": "bin/axusage"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "usage",
+    "analytics",
+    "cli",
+    "claude",
+    "chatgpt",
+    "gemini",
+    "copilot",
+    "llm",
+    "monitoring"
+  ],
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "dependencies": {
+    "@commander-js/extra-typings": "^14.0.0",
+    "axauth": "^1.0.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "env-paths": "^3.0.0",
+    "playwright": "^1.57.0",
+    "prom-client": "^15.1.3",
+    "trash": "^10.0.1",
+    "zod": "^4.2.0"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.0.0",
+    "@eslint/js": "^9.39.2",
+    "@total-typescript/ts-reset": "^0.6.1",
+    "@types/node": "^25.0.2",
+    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/eslint-plugin": "^1.5.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "fta-check": "^1.5.0",
+    "fta-cli": "^3.0.0",
+    "globals": "^16.5.0",
+    "knip": "^5.73.4",
+    "prettier": "3.7.4",
+    "semantic-release": "^25.0.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.49.0",
+    "vitest": "^4.0.15"
+  },
+  "scripts": {
+    "postinstall": "playwright install chromium",
+    "build": "tsc -p tsconfig.app.json",
+    "clean": "rm -rf dist *.tsbuildinfo",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "fta": "fta-check",
+    "knip": "knip",
+    "lint": "eslint",
+    "rebuild": "pnpm run clean && pnpm run build",
+    "start": "pnpm run rebuild && node bin/axusage",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest",
+    "typecheck": "tsc -b --noEmit"
+  }
+}