@smithers-orchestrator/usage 0.23.0

package/src/parseCodexUsage.js

@@ -0,0 +1,77 @@
+/** @typedef {import("./UsageWindow.ts").UsageWindow} UsageWindow */
+
+/**
+ * Maps a Codex rate-limit window's duration (in minutes) to a stable id/label.
+ * The Codex TUI labels windows the same way: ~300 min is the 5-hour window,
+ * ~10080 min is the weekly window.
+ *
+ * @param {number | undefined} minutes
+ * @param {string} fallbackId
+ * @returns {{ id: string; label: string }}
+ */
+function labelForMinutes(minutes, fallbackId) {
+    if (minutes === undefined) return { id: fallbackId, label: fallbackId };
+    if (minutes <= 60) return { id: "hourly", label: `${minutes}-minute` };
+    if (minutes < 1440) return { id: "5h", label: `${Math.round(minutes / 60)}-hour` };
+    if (minutes < 20160) return { id: "weekly", label: "weekly" };
+    return { id: "monthly", label: "monthly" };
+}
+
+/**
+ * Builds a percent window from a Codex `{ used_percent, window_minutes, reset_at }`
+ * block. `reset_at` is unix seconds.
+ *
+ * @param {unknown} block
+ * @param {string} fallbackId
+ * @returns {UsageWindow | undefined}
+ */
+function windowFrom(block, fallbackId) {
+    if (!block || typeof block !== "object") return undefined;
+    const b = /** @type {Record<string, unknown>} */ (block);
+    const usedPercent = typeof b.used_percent === "number" ? b.used_percent : undefined;
+    if (usedPercent === undefined) return undefined;
+    const minutes = typeof b.window_minutes === "number" ? b.window_minutes : undefined;
+    const { id, label } = labelForMinutes(minutes, fallbackId);
+    let resetsAt;
+    if (typeof b.reset_at === "number" && Number.isFinite(b.reset_at)) {
+        resetsAt = new Date(b.reset_at * 1000).toISOString();
+    }
+    return { id, label, unit: "percent", usedPercent, resetsAt };
+}
+
+/**
+ * Normalizes the Codex usage payload (from `GET /backend-api/wham/usage`, or the
+ * `codex.rate_limits` event) into windows plus plan and credit metadata. The
+ * rate-limit object may sit at the top level or under a `rate_limits` key; both
+ * shapes are accepted.
+ *
+ * @param {unknown} payload
+ * @returns {{ windows: UsageWindow[]; planType?: string; credits?: { hasCredits: boolean; unlimited: boolean; balance?: string } }}
+ */
+export function parseCodexUsage(payload) {
+    if (!payload || typeof payload !== "object") return { windows: [] };
+    const p = /** @type {Record<string, unknown>} */ (payload);
+    const rl = /** @type {Record<string, unknown>} */ (
+        p.rate_limits && typeof p.rate_limits === "object" ? p.rate_limits : p
+    );
+    const windows = [];
+    const primary = windowFrom(rl.primary, "primary");
+    if (primary) windows.push(primary);
+    const secondary = windowFrom(rl.secondary, "secondary");
+    if (secondary) windows.push(secondary);
+
+    const planRaw = p.plan_type ?? rl.plan_type;
+    const planType = typeof planRaw === "string" ? planRaw : undefined;
+
+    const creditsRaw = p.credits ?? rl.credits;
+    let credits;
+    if (creditsRaw && typeof creditsRaw === "object") {
+        const c = /** @type {Record<string, unknown>} */ (creditsRaw);
+        credits = {
+            hasCredits: Boolean(c.has_credits),
+            unlimited: Boolean(c.unlimited),
+            balance: typeof c.balance === "string" ? c.balance : undefined,
+        };
+    }
+    return { windows, planType, credits };
+}

package/src/parseDurationSeconds.js

@@ -0,0 +1,38 @@
+/**
+ * Parses a Go-style duration string into seconds. OpenAI's rate-limit reset
+ * headers use this format, e.g. `"1s"`, `"6m0s"`, `"1h2m3s"`, `"800ms"`.
+ *
+ * Returns `undefined` for input it cannot parse, so callers can omit a reset
+ * time rather than render a wrong one.
+ *
+ * @param {string | null | undefined} value
+ * @returns {number | undefined}
+ */
+export function parseDurationSeconds(value) {
+    if (value == null) return undefined;
+    const trimmed = value.trim();
+    if (trimmed === "") return undefined;
+    // Plain number of seconds, e.g. "30".
+    if (/^\d+(\.\d+)?$/.test(trimmed)) {
+        const n = Number(trimmed);
+        return Number.isFinite(n) ? n : undefined;
+    }
+    const re = /(\d+(?:\.\d+)?)(ms|us|µs|ns|s|m|h)/g;
+    let total = 0;
+    let matched = false;
+    let match;
+    while ((match = re.exec(trimmed)) !== null) {
+        matched = true;
+        const amount = Number(match[1]);
+        switch (match[2]) {
+            case "h": total += amount * 3600; break;
+            case "m": total += amount * 60; break;
+            case "s": total += amount; break;
+            case "ms": total += amount / 1000; break;
+            case "us":
+            case "µs": total += amount / 1_000_000; break;
+            case "ns": total += amount / 1_000_000_000; break;
+        }
+    }
+    return matched ? total : undefined;
+}

package/src/parseOpenAiRateLimitHeaders.js

@@ -0,0 +1,60 @@
+import { parseDurationSeconds } from "./parseDurationSeconds.js";
+
+/** @typedef {import("./UsageWindow.ts").UsageWindow} UsageWindow */
+
+/**
+ * @param {string | null | undefined} value
+ * @returns {number | undefined}
+ */
+function int(value) {
+    if (value == null) return undefined;
+    const n = parseInt(value, 10);
+    return Number.isNaN(n) ? undefined : n;
+}
+
+/**
+ * @param {(name: string) => string | null | undefined} get
+ * @param {string} suffix
+ * @param {string} id
+ * @param {string} label
+ * @param {number} nowMs
+ * @returns {UsageWindow | undefined}
+ */
+function countWindow(get, suffix, id, label, nowMs) {
+    const limit = int(get(`x-ratelimit-limit-${suffix}`));
+    const remaining = int(get(`x-ratelimit-remaining-${suffix}`));
+    if (limit === undefined && remaining === undefined) return undefined;
+    const resetSeconds = parseDurationSeconds(get(`x-ratelimit-reset-${suffix}`));
+    const used = limit !== undefined && remaining !== undefined ? limit - remaining : undefined;
+    return {
+        id,
+        label,
+        unit: "count",
+        limit,
+        remaining,
+        used,
+        resetsAt: resetSeconds !== undefined
+            ? new Date(nowMs + resetSeconds * 1000).toISOString()
+            : undefined,
+    };
+}
+
+/**
+ * Parses OpenAI rate-limit response headers into usage windows. OpenAI's reset
+ * headers are Go-duration strings relative to "now", so `nowMs` is added to
+ * produce an absolute ISO reset time (pass a fixed value in tests).
+ *
+ * Pass a getter, e.g. `(name) => response.headers.get(name)`.
+ *
+ * @param {(name: string) => string | null | undefined} get
+ * @param {number} [nowMs]
+ * @returns {UsageWindow[]}
+ */
+export function parseOpenAiRateLimitHeaders(get, nowMs = Date.now()) {
+    const windows = [];
+    const requests = countWindow(get, "requests", "requests-per-min", "requests/min", nowMs);
+    if (requests) windows.push(requests);
+    const tokens = countWindow(get, "tokens", "tokens-per-min", "tokens/min", nowMs);
+    if (tokens) windows.push(tokens);
+    return windows;
+}

package/src/publishedCaps.js

@@ -0,0 +1,29 @@
+/**
+ * Published daily request caps for Google providers, keyed by tier. Google does
+ * not expose a live "remaining quota" surface to a personal-login or API-key
+ * client, so any usage estimate must subtract local request counts from these
+ * documented caps. The numbers move (and the personal Code Assist tiers in the
+ * Gemini CLI stop serving 2026-06-18), so they live here as data, not logic.
+ *
+ * @type {Record<string, { label: string; requestsPerDay: number; rpm?: number }>}
+ */
+export const PUBLISHED_CAPS = {
+    "code-assist-free": { label: "Code Assist (free)", requestsPerDay: 1000, rpm: 60 },
+    "ai-pro": { label: "Google AI Pro", requestsPerDay: 1500 },
+    "ai-ultra": { label: "Google AI Ultra", requestsPerDay: 2000 },
+    "gemini-api-free": { label: "Gemini API (free tier)", requestsPerDay: 250 },
+    "code-assist-standard": { label: "Code Assist Standard", requestsPerDay: 1500 },
+    "code-assist-enterprise": { label: "Code Assist Enterprise", requestsPerDay: 2000 },
+};
+
+/**
+ * Looks up a published cap by tier id. Returns `undefined` for unknown tiers so
+ * the caller can degrade to "unknown" rather than invent a number.
+ *
+ * @param {string | undefined} tier
+ * @returns {{ label: string; requestsPerDay: number; rpm?: number } | undefined}
+ */
+export function publishedCapForTier(tier) {
+    if (!tier) return undefined;
+    return PUBLISHED_CAPS[tier];
+}

package/src/readClaudeCredentials.js

@@ -0,0 +1,69 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Reads the Claude Code subscription OAuth token for an account. Tries the
+ * account's `configDir/.credentials.json` first (the cross-platform location
+ * when `CLAUDE_CONFIG_DIR` is set), then falls back to the macOS Keychain item
+ * `Claude Code-credentials`.
+ *
+ * Returns `null` when no credential can be read, so the adapter degrades to a
+ * "none" report rather than throwing. The token is returned only to mint an
+ * outbound Authorization header; callers must never log or persist it.
+ *
+ * @param {{ configDir?: string }} account
+ * @param {NodeJS.Platform} [platform]
+ * @returns {{ accessToken: string; expiresAt?: number } | null}
+ */
+export function readClaudeCredentials(account, platform = process.platform) {
+    if (account.configDir) {
+        const path = join(account.configDir, ".credentials.json");
+        if (existsSync(path)) {
+            const parsed = parseCredentials(readFileSafe(path));
+            if (parsed) return parsed;
+        }
+    }
+    if (platform === "darwin") {
+        const result = spawnSync(
+            "security",
+            ["find-generic-password", "-s", "Claude Code-credentials", "-w"],
+            { stdio: ["ignore", "pipe", "ignore"], timeout: 4_000 },
+        );
+        if (result.status === 0) {
+            const parsed = parseCredentials(result.stdout?.toString("utf8") ?? "");
+            if (parsed) return parsed;
+        }
+    }
+    return null;
+}
+
+/**
+ * @param {string} path
+ * @returns {string}
+ */
+function readFileSafe(path) {
+    try {
+        return readFileSync(path, "utf8");
+    } catch {
+        return "";
+    }
+}
+
+/**
+ * @param {string} raw
+ * @returns {{ accessToken: string; expiresAt?: number } | null}
+ */
+function parseCredentials(raw) {
+    if (!raw.trim()) return null;
+    try {
+        const json = JSON.parse(raw);
+        const oauth = json?.claudeAiOauth;
+        const accessToken = oauth?.accessToken;
+        if (typeof accessToken !== "string" || accessToken === "") return null;
+        const expiresAt = typeof oauth?.expiresAt === "number" ? oauth.expiresAt : undefined;
+        return { accessToken, expiresAt };
+    } catch {
+        return null;
+    }
+}

package/src/readCodexCredentials.js

@@ -0,0 +1,41 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { decodeJwtClaims } from "./decodeJwtClaims.js";
+
+/**
+ * Reads the Codex ChatGPT-subscription OAuth token for an account from
+ * `configDir/auth.json` (the per-account `CODEX_HOME`). The ChatGPT account id
+ * comes from `tokens.account_id`, or failing that the `chatgpt_account_id`
+ * claim inside the `id_token` JWT.
+ *
+ * Returns `null` when no credential can be read or the account uses an API key
+ * instead of ChatGPT auth. The token is returned only to mint an outbound
+ * Authorization header.
+ *
+ * @param {{ configDir?: string }} account
+ * @returns {{ accessToken: string; accountId?: string } | null}
+ */
+export function readCodexCredentials(account) {
+    if (!account.configDir) return null;
+    const path = join(account.configDir, "auth.json");
+    if (!existsSync(path)) return null;
+    let json;
+    try {
+        json = JSON.parse(readFileSync(path, "utf8"));
+    } catch {
+        return null;
+    }
+    const tokens = json?.tokens;
+    const accessToken = tokens?.access_token;
+    if (typeof accessToken !== "string" || accessToken === "") return null;
+    let accountId = typeof tokens?.account_id === "string" ? tokens.account_id : undefined;
+    if (!accountId) {
+        const claims = decodeJwtClaims(tokens?.id_token);
+        const authClaim = /** @type {Record<string, unknown> | undefined} */ (
+            claims["https://api.openai.com/auth"]
+        );
+        const fromClaim = authClaim?.chatgpt_account_id;
+        if (typeof fromClaim === "string") accountId = fromClaim;
+    }
+    return { accessToken, accountId };
+}

package/src/usageCache.js

@@ -0,0 +1,55 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { accountsRoot } from "@smithers-orchestrator/accounts";
+
+/** @typedef {import("./UsageReport.ts").UsageReport} UsageReport */
+/** @typedef {{ version: 1; entries: Record<string, { report: UsageReport }> }} UsageCacheFile */
+
+/**
+ * Path to the on-disk usage cache. Lives next to `accounts.json` under the
+ * Smithers root so it honors `SMITHERS_HOME` in tests and CI.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function usageCachePath(env = process.env) {
+    return join(accountsRoot(env), "usage-cache.json");
+}
+
+/**
+ * Reads the usage cache, returning an empty cache when the file is missing or
+ * malformed (a cold cache is the normal startup state, not an error).
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {UsageCacheFile}
+ */
+export function readUsageCache(env = process.env) {
+    const path = usageCachePath(env);
+    if (!existsSync(path)) return { version: 1, entries: {} };
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed && typeof parsed === "object" && parsed.entries && typeof parsed.entries === "object") {
+            return { version: 1, entries: parsed.entries };
+        }
+    } catch {
+        // fall through to empty cache
+    }
+    return { version: 1, entries: {} };
+}
+
+/**
+ * Writes the usage cache atomically with mode 0600.
+ *
+ * @param {UsageCacheFile} contents
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string} the path written
+ */
+export function writeUsageCache(contents, env = process.env) {
+    const path = usageCachePath(env);
+    mkdirSync(accountsRoot(env), { recursive: true });
+    const tmp = `${path}.${process.pid}.tmp`;
+    writeFileSync(tmp, JSON.stringify(contents, null, 2), { mode: 0o600 });
+    // rename is atomic on the same filesystem
+    renameSync(tmp, path);
+    return path;
+}