@tsa-group/claude-usage 0.3.0

package/dist/util.js

@@ -0,0 +1,73 @@
+/** 小工具。沒有執行期依賴是刻意的 —— client 裝在同事機器上，每個 dependency
+ *  都是一個他們沒同意過的信任關係。 */
+import { createHash } from "node:crypto";
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+export const nowIso = (d = new Date()) => d.toISOString();
+/** ISO-8601 → Date，壞字串回 null（不丟例外：這些值來自外部 JSON） */
+export function parseIso(s) {
+    if (typeof s !== "string" || !s)
+        return null;
+    const t = Date.parse(s);
+    return Number.isNaN(t) ? null : new Date(t);
+}
+/** SHA256(s) 前 16 個十六進位字元。空值回 null —— 與 Python 版一致，
+ *  否則 `h16("")` 會變成一個看起來合法的雜湊。 */
+export function h16(s) {
+    if (!s)
+        return null;
+    return createHash("sha256").update(s, "utf8").digest("hex").slice(0, 16);
+}
+export function sha256hex(s) {
+    return createHash("sha256").update(s, "utf8").digest("hex");
+}
+export function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/** Atomic write —— 半寫的狀態檔會讓下一輪漏資料或重讀全部歷史。 */
+export function writeJsonAtomic(path, obj) {
+    const tmp = path + ".tmp";
+    writeFileSync(tmp, JSON.stringify(obj, null, 2) + "\n", "utf8");
+    renameSync(tmp, path);
+}
+/** 千分位，給本機檢視用 */
+export const fmtInt = (n) => n == null ? "-" : Math.round(n).toLocaleString("en-US");
+/** 大數字縮寫：284000000 → 284M。表格用，避免一欄吃掉整行 */
+export function fmtCompact(n) {
+    if (n == null)
+        return "-";
+    const a = Math.abs(n);
+    if (a >= 1e9)
+        return (n / 1e9).toFixed(1) + "B";
+    if (a >= 1e6)
+        return (n / 1e6).toFixed(1) + "M";
+    if (a >= 1e3)
+        return (n / 1e3).toFixed(0) + "K";
+    return String(Math.round(n));
+}
+/** 相對時間：in 3h 21m / 2h ago */
+export function humanDelta(iso) {
+    const t = parseIso(iso);
+    if (!t)
+        return "—";
+    const ms = t.getTime() - Date.now();
+    const past = ms < 0;
+    let secs = Math.abs(Math.round(ms / 1000));
+    const h = Math.floor(secs / 3600);
+    const m = Math.floor((secs % 3600) / 60);
+    const s = h ? `${h}h ${m}m` : `${m}m`;
+    return past ? `${s} ago` : `in ${s}`;
+}
+/** 本地時區的簡短時間戳 */
+export function localTime(iso, withDate = true) {
+    const t = parseIso(iso);
+    if (!t)
+        return "—";
+    const p = (n) => String(n).padStart(2, "0");
+    const hm = `${p(t.getHours())}:${p(t.getMinutes())}`;
+    return withDate ? `${p(t.getMonth() + 1)}-${p(t.getDate())} ${hm}` : hm;
+}

package/dist/version.js

@@ -0,0 +1,24 @@
+/**
+ * agent_version 的唯一來源 = package.json。
+ *
+ * 舊版另外維護一個 VERSION 檔，於是「發佈的版本」與「回報上去的版本」是兩個
+ * 可以各自漂移的數字 —— 而 agent_version 正是我們用來判斷「誰還在跑舊 client」
+ * 的欄位（server 端的裝置健康報表會顯示它），漂掉就等於這個欄位在說謊。
+ *
+ * 走執行期讀取而不是建置期產生：npm 打包一定會包含 package.json，且 src/ 與
+ * dist/ 到 package.json 的相對路徑相同，所以開發與出貨走的是同一條路徑。
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+function read() {
+    try {
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+export const VERSION = read();

package/dist/view.js

@@ -0,0 +1,182 @@
+/**
+ * 本機檢視。**刻意精簡**：數字全部保留，不做 box-drawing 邊框、進度條與 sparkline。
+ *
+ * 理由不只是省程式碼 —— 那些字元在 Windows console 與非 UTF-8 終端會變成亂碼，
+ * 而這個工具的重點是「同事願意裝、看得懂自己的數字」。真正的儀表在 BQ / Looker
+ * Studio，本機檢視只需要回答「我現在燒到哪、我這幾場 session 花了多少」。
+ *
+ * severity 的燈號有保留：那是 Anthropic 自己的判定（門檻未公開），是資訊不是裝飾。
+ */
+import { existsSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import * as events from "./events.js";
+import { lastSnapshot } from "./health.js";
+import { snapPath } from "./paths.js";
+import { fmtCompact, fmtInt, humanDelta, localTime } from "./util.js";
+const sevMark = (s) => ({ normal: "🟢", warning: "🟡", critical: "🔴" })[String(s)] ?? "⚪";
+/**
+ * 終端顯示寬度。CJK 與 emoji 在等寬終端佔 **2 格**，而 String.length 算 1 ——
+ * 直接用 length 補空白，中文標籤那幾欄就會歪掉（實測「5 小時窗」與「每週(全)」
+ * 對不齊）。這是這份精簡檢視唯一需要的排版邏輯。
+ */
+function dispWidth(s) {
+    let w = 0;
+    for (const ch of s) {
+        const c = ch.codePointAt(0);
+        const wide = (c >= 0x1100 && c <= 0x115f) || // Hangul Jamo
+            (c >= 0x2e80 && c <= 0xa4cf) || // CJK 部首、假名、漢字
+            (c >= 0xac00 && c <= 0xd7a3) || // Hangul 音節
+            (c >= 0xf900 && c <= 0xfaff) || // CJK 相容漢字
+            (c >= 0xfe30 && c <= 0xfe6f) || // CJK 相容形式
+            (c >= 0xff00 && c <= 0xff60) || // 全形英數
+            (c >= 0xffe0 && c <= 0xffe6) ||
+            (c >= 0x1f300 && c <= 0x1faff); // emoji（severity 燈號）
+        w += wide ? 2 : 1;
+    }
+    return w;
+}
+const pad = (s, n) => {
+    const gap = n - dispWidth(s);
+    return gap > 0 ? s + " ".repeat(gap) : s;
+};
+const padL = (s, n) => {
+    const gap = n - dispWidth(s);
+    return gap > 0 ? " ".repeat(gap) + s : s;
+};
+/** 最新一筆快照 */
+export function showLatest() {
+    const snap = lastSnapshot();
+    if (!snap) {
+        console.log("尚無快照 — 先跑：claude-usage sample");
+        return 1;
+    }
+    const u = (snap["usage"] ?? {});
+    const limits = (Array.isArray(u["limits"]) ? u["limits"] : []);
+    const byKind = new Map(limits.map((l) => [String(l["kind"]), l]));
+    console.log(`\n採集 ${localTime(snap["collected_at"])} (${humanDelta(snap["collected_at"])})  ` +
+        `訂閱=${snap["subscription"] ?? "-"}  tier=${snap["tier"] ?? "-"}  ` +
+        `creds=${snap["cred_source"] ?? "-"}\n`);
+    const line = (label, pct, sev, resets, extra = "") => console.log(`  ${pad(label, 14)}${padL(pct == null ? "-" : `${pct}%`, 5)}  ${sevMark(sev)} ${pad(String(sev ?? "-"), 9)}` +
+        `reset ${humanDelta(resets)}${extra}`);
+    const fh = (u["five_hour"] ?? {});
+    const sd = (u["seven_day"] ?? {});
+    const sess = byKind.get("session") ?? {};
+    const wall = byKind.get("weekly_all") ?? {};
+    const wsc = byKind.get("weekly_scoped");
+    line("5 小時窗", fh["utilization"], sess["severity"], fh["resets_at"]);
+    line("每週(全)", sd["utilization"], wall["severity"], sd["resets_at"]);
+    if (wsc) {
+        const scope = (wsc["scope"] ?? {});
+        const model = (scope["model"] ?? {})["display_name"];
+        // per-model 週上限。它**只存在於 limits[] 裡**，不在 usage.five_hour/seven_day，
+        // 是「週額度是不是被單一模型吃掉」的唯一訊號。
+        line("每週(單模型)", wsc["percent"], wsc["severity"], wsc["resets_at"], `  [${model ?? "?"}]`);
+    }
+    const ex = (u["extra_usage"] ?? {});
+    console.log(`\n  overage: enabled=${ex["is_enabled"]}  spend_limit_reached=${ex["spend_limit_reached"]}`);
+    console.log("  註：此為帳號全域額度（含 claude.ai 網頁 chat），與下面的 token 數是兩個獨立指標\n");
+    return 0;
+}
+/** 快照時間序（表格，不畫圖） */
+export function showHistory() {
+    const p = snapPath();
+    if (!existsSync(p)) {
+        console.log("尚無快照");
+        return 1;
+    }
+    const rows = [];
+    for (const l of readFileSync(p, "utf8").split("\n")) {
+        if (!l.trim())
+            continue;
+        try {
+            rows.push(JSON.parse(l));
+        }
+        catch {
+            continue;
+        }
+    }
+    if (!rows.length) {
+        console.log("快照檔是空的");
+        return 1;
+    }
+    console.log(`\n${rows.length} 筆快照\n`);
+    console.log(`  ${pad("時間", 16)}${padL("5h%", 6)}${padL("week%", 7)}  5h reset`);
+    let prev = null;
+    for (const r of rows) {
+        const u = (r["usage"] ?? {});
+        const fh = (u["five_hour"] ?? {});
+        const sd = (u["seven_day"] ?? {});
+        const fv = Number(fh["utilization"] ?? 0);
+        const wv = Number(sd["utilization"] ?? 0);
+        // 下降 = 窗 reset 了（窗內 utilization 單調遞增），標出來讓人看得到窗邊界
+        const trend = prev === null ? "" : fv > prev ? `  +${(fv - prev).toFixed(0)}` : fv < prev ? "  reset" : "";
+        console.log(`  ${pad(localTime(r["collected_at"]), 16)}${padL(fv.toFixed(0), 6)}${padL(wv.toFixed(0), 7)}  ` +
+            `${localTime(fh["resets_at"])}${trend}`);
+        prev = fv;
+    }
+    console.log();
+    return 0;
+}
+/** session / token 明細 */
+export function showSessions(argv = []) {
+    const ev = events.extract();
+    const agg = new Map();
+    for (const e of ev) {
+        const sid = e.session_id;
+        if (!sid)
+            continue;
+        let s = agg.get(sid);
+        if (!s) {
+            s = {
+                id: sid, first: e.ts, last: e.ts, msgs: 0, sub: 0, models: new Set(),
+                input: 0, output: 0, cacheRead: 0, w5m: 0, w1h: 0,
+            };
+            agg.set(sid, s);
+        }
+        if (e.ts < s.first)
+            s.first = e.ts;
+        if (e.ts > s.last)
+            s.last = e.ts;
+        s.msgs++;
+        if (e.is_sidechain)
+            s.sub++;
+        if (e.model)
+            s.models.add(e.model);
+        s.input += e.input_tokens ?? 0;
+        s.output += e.output_tokens ?? 0;
+        s.cacheRead += e.cache_read_tokens ?? 0;
+        s.w5m += e.cache_write_5m_tokens ?? 0;
+        s.w1h += e.cache_write_1h_tokens ?? 0;
+    }
+    const recs = [...agg.values()].sort((a, b) => (a.first < b.first ? -1 : 1));
+    if (argv.includes("--json")) {
+        console.log(JSON.stringify({ schema: "sessions.v2", sessions: recs.map((r) => ({ ...r, models: [...r.models].sort() })) }, null, 2));
+        return 0;
+    }
+    const hdr = `  ${pad("session", 14)}${pad("start", 14)}${padL("msgs", 6)}${padL("sub", 5)}` +
+        `${padL("in", 8)}${padL("out", 8)}${padL("cache_rd", 10)}${padL("cache_wr", 10)}  models`;
+    console.log("\n" + hdr);
+    console.log("  " + "-".repeat(hdr.length - 2));
+    const tot = { msgs: 0, sub: 0, input: 0, output: 0, cacheRead: 0, w5m: 0, w1h: 0 };
+    for (const r of recs) {
+        tot.msgs += r.msgs;
+        tot.sub += r.sub;
+        tot.input += r.input;
+        tot.output += r.output;
+        tot.cacheRead += r.cacheRead;
+        tot.w5m += r.w5m;
+        tot.w1h += r.w1h;
+        console.log(`  ${pad(r.id.slice(0, 12), 14)}${pad(localTime(r.first), 14)}${padL(String(r.msgs), 6)}` +
+            `${padL(String(r.sub), 5)}${padL(fmtCompact(r.input), 8)}${padL(fmtCompact(r.output), 8)}` +
+            `${padL(fmtCompact(r.cacheRead), 10)}${padL(fmtCompact(r.w5m + r.w1h), 10)}  ` +
+            [...r.models].map((m) => m.replace("claude-", "")).sort().join(","));
+    }
+    console.log("  " + "-".repeat(hdr.length - 2));
+    console.log(`  ${pad("TOTAL", 14)}${pad(`${recs.length} sessions`, 14)}${padL(String(tot.msgs), 6)}` +
+        `${padL(String(tot.sub), 5)}${padL(fmtCompact(tot.input), 8)}${padL(fmtCompact(tot.output), 8)}` +
+        `${padL(fmtCompact(tot.cacheRead), 10)}${padL(fmtCompact(tot.w5m + tot.w1h), 10)}`);
+    console.log(`\n  cache_write 拆開：5m=${fmtInt(tot.w5m)} (base x1.25)  1h=${fmtInt(tot.w1h)} (base x2)`);
+    console.log("  sub = subagent 訊息數");
+    console.log("  刻意不印 tokens 總和：cache_read 單價只有 base 的 0.1x，加總後會被它完全主導而失去意義\n");
+    return 0;
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@tsa-group/claude-usage",
+  "version": "0.3.0",
+  "description": "Per-user Claude usage collector — measures Claude Code token detail and account-level rate-limit utilization locally, reports to your own ingest server.",
+  "type": "module",
+  "bin": { "claude-usage": "dist/cli.js" },
+  "files": ["dist", "README.md"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --test test/*.test.ts",
+    "prepublishOnly": "npm run build && npm test",
+    "check": "tsc -p tsconfig.json --noEmit"
+  },
+  "keywords": ["claude", "usage", "telemetry", "cli"],
+  "license": "UNLICENSED",
+  "private": false,
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0"
+  }
+}