tokenusage-cli 0.4.3 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -3,6 +3,72 @@
3
3
  本包(`tokenusage-cli`)的用户可见变更记录。发版时在顶部新增一节,
4
4
  `## <版本号>` 行会被 release workflow 取作 GitHub Release 正文。
5
5
 
6
+ ## 0.4.5
7
+
8
+ 2026-11-04。一轮审计修复:`sync` 读队列时把契约 v2 的项目拆分行压回余量行、随后照旧推进
9
+ 上传偏移,被归因的用量会永久丢失;上传确认、Windows 隐藏启动器编码与首同步统计也各有一处
10
+ 缺陷。无契约变更,服务端无需同步升级。
11
+
12
+ - **队列批次不再丢项目行**:`readQueueBatch` 的去重键原来只有 `source|model|hour`,
13
+ 契约 v2 的拆分行(同键不同 `project_key`)会被合并成余量行并随偏移推进永久丢失;
14
+ 现键含 `project_key`,每行独立上传。
15
+ - **拆分行按服务端 basename 身份合并**:写出/合并项目拆分行时统一走共享的
16
+ `lib/project-key.js`(`basenameKey()`),与服务端请求去重口径一致;同名不同 owner 的
17
+ 仓库不再互相覆盖。`reconcile` 对旧的 `owner/repo` 行做同样的归一,避免把正常数据报成漂移。
18
+ - **上传确认后才推进进度**:`ingest` 需响应含 `inserted` + `skipped`、session 上传需含
19
+ `sessions_upserted` + `sessions_skipped`,才推进队列偏移 / watermark;未确认的 2xx
20
+ 响应按失败处理,下次 `sync` 重传而不是静默跳数据。
21
+ - **Windows 隐藏启动器改 UTF-16LE + BOM**:`run-sync-hidden.vbs` 按 wscript 期望的编码
22
+ 写入,含非 ASCII 字符的安装路径不再乱码或被截断。
23
+ - **首同步统计修正**:`init` 的首次同步统计跳过 `kind` 控制行,并把 `project_key` 纳入
24
+ last-wins 键,项目用量不再被余量行盖掉。
25
+ - 回归测试:拆分行往返、basename 归一、VBS 编码、未确认 2xx 不推进偏移/watermark。
26
+
27
+ ## 0.4.4
28
+
29
+ 2026-11-04。契约 v2 落地:小时用量桶按项目名拆行(`project_key`),项目键向上回退到真实
30
+ 项目目录;新增 DeepSeek 余额/状态卡、`status --json` 的计价出处块、`doctor` 计价覆盖自检;
31
+ curated 定价扩到 191 条,Cursor / Kimi / Grok 限额卡补磁盘缓存回退。旧 `tokentracker-*`
32
+ 别名已在服务端移除,仍打旧路径的钉版客户端会得到有声失败(GET 404 / 写动词 405),本地队列不丢。
33
+
34
+ - **服务端 breaking:旧 `tokentracker-*` API 路径别名已移除**(契约 §1.5,2026-11-03
35
+ 操作者拍板)。指向本后端的钉版旧 CLI(tokentracker-cli@1.4.x)上传会得到
36
+ GET 404 / 写动词 405——有声失败、本地 `queue.jsonl` 数据保留,升级到本包后随下次
37
+ `sync` 补传,不丢历史。
38
+ - **桶级 `project_key`(契约 v2,2026-11-03)**:小时用量桶按项目名拆行——每个项目一行,
39
+ 再加一条 `project_key` 为空的余量行,两者相加等于原聚合值,不重复计数;无法归因的
40
+ 历史/账户级用量留在余量行(`docs/cli-contract.md` §2.4、`docs/projects-page-plan.md` §5)。
41
+ - **项目键父级回退(2026-11-04)**:`projectKey()` 不再把 `<repo>/.claude/worktrees/<id>`、
42
+ `<repo>/worktrees/<id>`、`<project>/<session>/subagents` 这类工具目录当成项目名,而是向上
43
+ 取真实项目目录;qoder-cn 子代理转录继承记录里的 `cwd`。只影响新采集——历史键不回填
44
+ (会话落库键含 `session_id`,同会话只更新不改名)。`~/.codex/worktrees/<id>` 无上游项目
45
+ 规则,保持旧行为。
46
+ - **新增 DeepSeek 余额卡与 DeepSeek 服务状态**:`status` 限额面板新增第 18 家提供商
47
+ (pay-as-you-go 余额,含 12h TTL 磁盘缓存与 API key 指纹绑定,凭据错误不回退缓存),
48
+ 服务状态探测接入 status.deepseek.com。
49
+ - **`status --json` 暴露计价数据出处**:新增 `pricing` 块(数据来源、seed 快照日期、
50
+ LiteLLM/curated 条目数),成本为 0 时可直接区分「未采集」与「未定价」。
51
+ - **`doctor` 新增计价覆盖自检**:近 7 天本地队列的桶/token 计价命中率、Top 未定价模型
52
+ (零 token 的积分桶单独计数、不再误报),以及 unknown 模型「对齐到同时段主导模型」的
53
+ 只读 dry-run 预览(不改变任何历史归属)。
54
+ - **计价覆盖大幅扩充**:curated exact 91 → 191。同步上游 TokenTracker 新增的 29+9 条
55
+ (claude-opus-4-5/4-6、gpt-5.4/5.5 系、kimi-k3.1-pro 等);从 juejin-usage 选摘
56
+ volcengine/alibaba-cn/xiaomi/muse 四组 69 条(署名见 THIRD_PARTY_NOTICES);补
57
+ Unisound `u2-flash` 与 StepFun `step-5-preview` 官价。本机 7 天窗口 token 计价覆盖率
58
+ 97.3% → 100%。
59
+ - **Cursor / Kimi / Grok 限额卡新增磁盘缓存回退**:请求超时或 5xx 时展示最近一次成功
60
+ 读数(卡片标 `stale` + 原 `cached_at`),不再整卡空白。缓存文件各为
61
+ `cursor/kimi/grok-usage-limits-cache.json`(`~/.tokenusage/tracker/`,0600 原子写、
62
+ 只在成功时写、reset_at 已过期的窗口自动丢弃);身份指纹绑定(cursor=规范
63
+ userId、kimi=profile 标识、grok=JWT sub),换号不串用;凭据类错误(401/403/过期)
64
+ 不回退、原样上面板。**全部 limits 磁盘缓存的 stale TTL 统一为 12h**(含既有的
65
+ claude/codex/opencodeGo/antigravity/qoder 五家与 DeepSeek 余额卡——额度/余额类读数
66
+ 一天内即过时;qoder 促销活动缓存 24h、opencodeGo 本地估算缓存 1h 属不同语义,不动)。
67
+ - 单测:`pricing-parity`(CLI/web 两份定价数据逐字节一致守卫)、`pricing-meta`、
68
+ `pricing-coverage`、`deepseek-limits` / `deepseek-status`,以及
69
+ `cursor/grok/kimi-limits-cache-fallback`(命中/过期/失败回退/换号不串用/凭据错误直通/
70
+ 无缓存失败,共 22 例)。
71
+
6
72
  ## 0.4.3
7
73
 
8
74
  2026-11-01。两处只有真机首跑才暴露的问题:调度摘要依旧看不出拒绝原因(修的过程中又追出
@@ -11,6 +11,21 @@ upstream repository and were then modified for the token-usage contract
11
11
  (`docs/cli-contract.md` in the repository root). The upstream MIT license text
12
12
  and copyright notice are preserved in this package's `LICENSE` file.
13
13
 
14
- 本包不含其他第三方资产:运行时依赖(如 `undici`)的许可随
15
- `node_modules` 一同分发;品牌图标、字体与定价快照属于 Web 端,登记在仓库根目录的
14
+ ## juejin-usage (pricing data)
15
+
16
+ `src/lib/pricing/curated-overrides.json` 中的 volcengine / xiaomi / meta(muse) /
17
+ alibaba-cn / moonshotai-cn 五组共 69 条 exact 定价条目(2026-11-03 导入)取自
18
+ [juejin-usage](https://github.com/juejin-cn/juejin-usage)(MIT License,
19
+ Copyright (c) juejin-cn)commit `f72ca4d` 的 `packages/core/src/pricing/pricing.json`
20
+ (models.dev 官方渠道价格集)。juejin-usage 的 MIT 许可要求复制时保留其版权与许可声明:
21
+
22
+ > MIT License, Copyright (c) 2026 juejin-cn — Permission is hereby granted,
23
+ > free of charge, to any person obtaining a copy of this software and
24
+ > associated documentation files, to deal in the Software without restriction,
25
+ > subject to the condition that the above copyright notice and this permission
26
+ > notice shall be included in all copies or substantial portions of the
27
+ > Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
28
+
29
+ 本包其余部分不含其他第三方资产:运行时依赖(如 `undici`)的许可随
30
+ `node_modules` 一同分发;品牌图标、字体与定价快照(LiteLLM seed)的登记见仓库根目录的
16
31
  `THIRD_PARTY_NOTICES.md`。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tokenusage-cli",
3
- "version": "0.4.3",
3
+ "version": "0.4.5",
4
4
  "description": "Self-hosted AI coding token usage collector for the Token Usage dashboard.",
5
5
  "keywords": [
6
6
  "token-usage",
@@ -41,9 +41,9 @@
41
41
  "prepublishOnly": "npm test"
42
42
  },
43
43
  "dependencies": {
44
- "@journeyapps/wa-sqlite": "2.0.7",
45
- "smol-toml": "^1.9.0",
46
- "undici": "8.12.2",
44
+ "@journeyapps/wa-sqlite": "2.0.10",
45
+ "smol-toml": "^1.9.1",
46
+ "undici": "8.12.3",
47
47
  "yauzl": "^3.4.0"
48
48
  },
49
49
  "pnpm": {
@@ -2807,7 +2807,14 @@ function readFirstSyncTotals(trackerDir) {
2807
2807
  if (!trimmed) continue;
2808
2808
  try {
2809
2809
  const row = JSON.parse(trimmed);
2810
- const key = `${row.source || ""}|${row.model || ""}|${row.hour_start || ""}`;
2810
+ // Control records (account session states / watermarks) carry a
2811
+ // `total_tokens` too; they are not usage buckets and must not inflate
2812
+ // the first-sync counter.
2813
+ if (!row || typeof row !== "object" || Object.hasOwn(row, "kind")) continue;
2814
+ // Contract v2: project_key joins the last-wins identity. Without it the
2815
+ // residual row (appended last) hides every attributed project row, and a
2816
+ // fully attributed hour would display as 0 tokens.
2817
+ const key = `${row.source || ""}|${row.model || ""}|${row.hour_start || ""}|${row.project_key || ""}`;
2811
2818
  latest.set(key, row);
2812
2819
  } catch {
2813
2820
  // skip malformed
@@ -40,6 +40,7 @@ const { functionUrlFor, fetchFunctionResponse } = require("../lib/function-url")
40
40
  const { iterateQueueLines } = require("../lib/upload-queue");
41
41
  const { normalizeQueueRow } = require("../lib/queue-row-normalize");
42
42
  const { sanitizeBucketForUpload } = require("../lib/ingest-sanitize");
43
+ const { basenameKey } = require("../lib/project-key");
43
44
  const { TOKEN_COLUMNS } = require("../lib/account-usage-dedup");
44
45
  const { UsageError, unknownOptionError } = require("../lib/cli-errors");
45
46
 
@@ -161,9 +162,11 @@ function resolveWindow(opts, nowMs) {
161
162
  return { fromMs: clampedFrom, toMs, clamped: clampedFrom !== effectiveFrom };
162
163
  }
163
164
 
164
- function bucketKey(hourMs, source, model) {
165
- // JSON over a delimiter: model names may contain `|`.
166
- return JSON.stringify([new Date(hourMs).toISOString(), source, model]);
165
+ function bucketKey(hourMs, source, model, project = "") {
166
+ // JSON over a delimiter: model names may contain `|`. contract v2
167
+ // (2026-11-03): project_key joins the identity; '' = unattributed (rows
168
+ // from a pre-v2 server have no project_key at all and land here too).
169
+ return JSON.stringify([new Date(hourMs).toISOString(), source, model, project]);
167
170
  }
168
171
 
169
172
  // Local baseline: every usage row in queue.jsonl, normalized/sanitized exactly
@@ -206,7 +209,14 @@ async function collectBuckets({ queuePath, fromMs, toMs, start = 0 }) {
206
209
  });
207
210
  const sanitized = sanitizeBucketForUpload(row);
208
211
  if (!sanitized) continue;
209
- buckets.set(bucketKey(hourMs, source, model), sanitized);
212
+ // The server stores only the basename (§2.4). Normalizing here keeps
213
+ // pre-v2 queues whose rows still carry `owner/repo` comparable with the
214
+ // cloud instead of reporting permanent missing_on_server drift.
215
+ const project =
216
+ typeof sanitized.project_key === "string"
217
+ ? basenameKey(sanitized.project_key) || ""
218
+ : "";
219
+ buckets.set(bucketKey(hourMs, source, model, project), sanitized);
210
220
  }
211
221
  } finally {
212
222
  await handle.close();
@@ -283,7 +293,9 @@ async function fetchServerBuckets({ baseUrl, anonKey, deviceToken, from, to, lim
283
293
  if (!Number.isFinite(hourMs)) continue;
284
294
  const source = String(row.source);
285
295
  const model = String(row.model);
286
- buckets.set(bucketKey(hourMs, source, model), row);
296
+ // Pre-v2 servers omit project_key entirely; treat as unattributed ('').
297
+ const project = typeof row.project_key === "string" ? row.project_key : "";
298
+ buckets.set(bucketKey(hourMs, source, model, project), row);
287
299
  }
288
300
  if (rows.length < pageSize) break;
289
301
  offset += rows.length;
@@ -48,6 +48,7 @@ const {
48
48
  } = require("../lib/openclaw-session-plugin");
49
49
  const { resolveTrackerPaths } = require("../lib/tracker-paths");
50
50
  const { resolveDeviceTokenPresence } = require("../lib/cloud-device-token");
51
+ const { getPricingMeta } = require("../lib/pricing");
51
52
  const {
52
53
  isCollectionPaused,
53
54
  isRunReportEnabled,
@@ -1281,6 +1282,9 @@ async function cmdStatus(argv = []) {
1281
1282
  }
1282
1283
  : {}),
1283
1284
  subscriptions,
1285
+ // Pricing data provenance + staleness, so a $0 cost row can be triaged
1286
+ // as "not collected" vs "not priced" from `status --json` alone.
1287
+ pricing: getPricingMeta(),
1284
1288
  };
1285
1289
 
1286
1290
  if (opts.json) {
@@ -4721,6 +4721,14 @@ async function drainQueueToCloud({ baseUrl, anonKey, deviceToken, queuePath, que
4721
4721
  throw err;
4722
4722
  }
4723
4723
 
4724
+ if (!isConfirmedIngestResponse(data)) {
4725
+ const err = new Error(
4726
+ `Unconfirmed ingest response (HTTP ${res.status}): ${rawText.substring(0, 300)}`,
4727
+ );
4728
+ err.status = res.status;
4729
+ err.code = "CLOUD_UPLOAD_UNCONFIRMED";
4730
+ throw err;
4731
+ }
4724
4732
  cloudAccess = data;
4725
4733
  if (data.upload_scope === "community") batchBudget = Math.min(batchBudget, 10);
4726
4734
  inserted += Number(data?.inserted || 0);
@@ -4755,6 +4763,23 @@ async function drainQueueToCloud({ baseUrl, anonKey, deviceToken, queuePath, que
4755
4763
  return resultSoFar();
4756
4764
  }
4757
4765
 
4766
+ // A 200 is not proof the ingest committed: captive portals / reverse proxies
4767
+ // return 200 HTML and maintenance pages return an empty body. Advancing the
4768
+ // queue offset on those silently drops the batch forever, so the drain only
4769
+ // accepts the contract's success shape (docs/cli-contract.md §2.4).
4770
+ function isCount(value) {
4771
+ return (
4772
+ (typeof value === "number" || typeof value === "string") &&
4773
+ value !== "" &&
4774
+ Number.isFinite(Number(value))
4775
+ );
4776
+ }
4777
+
4778
+ function isConfirmedIngestResponse(data) {
4779
+ return Boolean(data) && typeof data === "object" && !Array.isArray(data) &&
4780
+ isCount(data.inserted) && isCount(data.skipped);
4781
+ }
4782
+
4758
4783
  async function readQueueBatch(queuePath, startOffset, maxBuckets) {
4759
4784
  const st = await fs.stat(queuePath).catch(() => null);
4760
4785
  if (!st || !st.isFile()) return { buckets: [], sessionStates: [], nextOffset: startOffset };
@@ -4862,7 +4887,17 @@ async function readQueueBatch(queuePath, startOffset, maxBuckets) {
4862
4887
  // otherwise 400 the whole ingest batch and stall the queue.
4863
4888
  const sanitized = sanitizeBucketForUpload(bucket);
4864
4889
  if (!sanitized) continue;
4865
- bucketMap.set(`${source}|${model}|${hourStart}`, sanitized);
4890
+ // Contract v2: project_key is part of the bucket identity. Split hours
4891
+ // carry several rows with the same (source, model, hour) under different
4892
+ // project keys (plus the '' residual); omitting it here collapsed them
4893
+ // to the last row and then advanced the offset past the rest, losing the
4894
+ // attributed usage permanently. New queue rows already carry the
4895
+ // server-normalized basename (rollout's appendProjectSplitRows); old
4896
+ // owner/repo rows stay distinct here and let the server's own basename
4897
+ // dedupe pick the larger total instead of collapsing them locally.
4898
+ const projectKey =
4899
+ typeof sanitized.project_key === "string" ? sanitized.project_key.trim() : "";
4900
+ bucketMap.set(`${source}|${model}|${hourStart}|${projectKey}`, sanitized);
4866
4901
  linesRead += 1;
4867
4902
  if (linesRead >= maxBuckets) break;
4868
4903
  }
@@ -242,7 +242,11 @@ function fetchCursorUsageSummary({ cookie, timeoutMs = 30000, fetchImpl = fetch
242
242
  signal: AbortSignal.timeout(timeoutMs),
243
243
  }).then(async (res) => {
244
244
  if (res.status === 401 || res.status === 403) {
245
- throw new Error("Cursor session expired — re-login in Cursor to refresh");
245
+ // The code marks the error actionable (re-login) so the limits
246
+ // disk-cache fallback never hides it.
247
+ const error = new Error("Cursor session expired — re-login in Cursor to refresh");
248
+ error.code = "AUTH_EXPIRED";
249
+ throw error;
246
250
  }
247
251
  if (!res.ok) {
248
252
  throw new Error(`Cursor API returned ${res.status}`);
@@ -0,0 +1,280 @@
1
+ "use strict";
2
+
3
+ // DeepSeek (platform.deepseek.com, pay-as-you-go) balance monitoring.
4
+ //
5
+ // DeepSeek has no quota windows at all: it is a prepaid API platform, and the
6
+ // only documented programmatic data source is the balance endpoint
7
+ // (GET https://api.deepseek.com/user/balance, Bearer API key). It returns
8
+ // `is_available` plus `balance_infos[]` entries whose numeric fields are all
9
+ // STRINGS ("110.02"), and more than one currency (CNY + USD) can be present
10
+ // at the same time. Concurrency rate limits (flash 2500 / v4-pro 500, 429)
11
+ // are not quota windows, so nothing here produces a window bar — the panel
12
+ // renders a balance card instead (issue #960).
13
+ //
14
+ // The API key comes from DEEPSEEK_API_KEY when set, otherwise from the key
15
+ // saved in the Limits panel (provider-api-key-store.js). The stored key exists
16
+ // so users never need a machine-wide `launchctl setenv`, which reaches every
17
+ // launchd app on macOS and not just Token Usage (#837).
18
+ //
19
+ // Balance only decreases between top-ups and there is no reset instant to
20
+ // check, so the last-good disk-cache fallback (0600 JSON, written only on a
21
+ // live success) is gated by a pure TTL — the same "unknown reset" rule the
22
+ // ark providers use — and by a fingerprint of the API key that produced it,
23
+ // so a swapped key can never serve the previous account's balance.
24
+
25
+ const crypto = require("node:crypto");
26
+ const fs = require("node:fs");
27
+ const os = require("node:os");
28
+ const path = require("node:path");
29
+ const { readStoredApiKey } = require("./provider-api-key-store");
30
+
31
+ const DEEPSEEK_BALANCE_URL = "https://api.deepseek.com/user/balance";
32
+ const DEEPSEEK_LIMITS_CACHE_FILE = "deepseek-limits-cache.json";
33
+ const DEEPSEEK_ENV_NAME = "DEEPSEEK_API_KEY";
34
+ const DEEPSEEK_REQUEST_TIMEOUT_MS = 10_000;
35
+ const DEEPSEEK_BALANCE_CACHE_TTL_MS = 12 * 60 * 60 * 1000;
36
+
37
+ function readDeepseekApiKey({ home, trackerDir, env = process.env } = {}) {
38
+ const envKey =
39
+ env && typeof env === "object" && typeof env[DEEPSEEK_ENV_NAME] === "string"
40
+ ? env[DEEPSEEK_ENV_NAME].trim()
41
+ : "";
42
+ if (envKey) return { apiKey: envKey, source: "env" };
43
+ const stored = readStoredApiKey({ provider: "deepseek", trackerDir, home });
44
+ return stored ? { apiKey: stored, source: "stored" } : null;
45
+ }
46
+
47
+ // Balance payloads are strings; a malformed or negative entry must drop out
48
+ // rather than coerce into a misleading 0 ("" and " " both coerce to 0).
49
+ function balanceNumber(value) {
50
+ if (typeof value === "string") {
51
+ const trimmed = value.trim();
52
+ if (!trimmed) return null;
53
+ const n = Number(trimmed);
54
+ return Number.isFinite(n) && n >= 0 ? n : null;
55
+ }
56
+ if (typeof value !== "number") return null;
57
+ return Number.isFinite(value) && value >= 0 ? value : null;
58
+ }
59
+
60
+ /**
61
+ * Normalize the GET /user/balance payload into one row per currency, API
62
+ * order preserved (the panel renders each currency side by side; picking a
63
+ * single "primary" currency is an owner decision, not a parser concern).
64
+ * Throws when the payload shape is unusable so the caller can fall back to
65
+ * the disk cache.
66
+ */
67
+ function normalizeDeepseekBalanceResponse(body) {
68
+ if (!body || typeof body !== "object") {
69
+ throw new Error("DeepSeek balance response is not an object.");
70
+ }
71
+ if (typeof body.is_available !== "boolean") {
72
+ throw new Error("DeepSeek balance response is missing is_available.");
73
+ }
74
+ const entries = Array.isArray(body.balance_infos) ? body.balance_infos : [];
75
+ const balances = [];
76
+ for (const entry of entries) {
77
+ const currency = typeof entry?.currency === "string" ? entry.currency.trim() : "";
78
+ const total = balanceNumber(entry?.total_balance);
79
+ if (!currency || total === null) continue;
80
+ balances.push({
81
+ currency,
82
+ total,
83
+ granted: balanceNumber(entry?.granted_balance) ?? 0,
84
+ topped_up: balanceNumber(entry?.topped_up_balance) ?? 0,
85
+ });
86
+ }
87
+ if (balances.length === 0) {
88
+ throw new Error("DeepSeek balance response contains no usable balance entries.");
89
+ }
90
+ return balances;
91
+ }
92
+
93
+ // The fingerprint labels a credential, so it must come from a memory-hard
94
+ // KDF rather than a bare fast hash (CodeQL flags sha256 over key-store/env
95
+ // credentials; the ark apiKey-prefix label hit the same alert before #950).
96
+ // Memoized per key: scrypt is intentionally slow.
97
+ const DEEPSEEK_FINGERPRINT_SALT = "tokenusage/deepseek-limits-cache/v1";
98
+ let fingerprintMemo = null;
99
+
100
+ function keyFingerprint(apiKey) {
101
+ const key = String(apiKey);
102
+ if (fingerprintMemo?.key === key) return fingerprintMemo.hex;
103
+ const hex = crypto
104
+ .scryptSync(key, DEEPSEEK_FINGERPRINT_SALT, 16, {
105
+ N: 2 ** 15,
106
+ r: 8,
107
+ p: 1,
108
+ maxmem: 128 * 2 ** 15 * 8 * 2,
109
+ })
110
+ .toString("hex");
111
+ fingerprintMemo = { key, hex };
112
+ return hex;
113
+ }
114
+
115
+ function resolveDeepseekLimitsCachePath({ trackerDir, home } = {}) {
116
+ const dir =
117
+ typeof trackerDir === "string" && trackerDir.trim()
118
+ ? trackerDir.trim()
119
+ : path.join(home || os.homedir(), ".tokenusage", "tracker");
120
+ return path.join(dir, DEEPSEEK_LIMITS_CACHE_FILE);
121
+ }
122
+
123
+ /**
124
+ * Last-good balance snapshot. `keyFingerprint` (when given) must match the
125
+ * key that produced the cache — a different key is a different account, and
126
+ * its balance would be a wrong answer, not a stale one.
127
+ */
128
+ function readDeepseekLimitsCache({ trackerDir, home, nowMs = Date.now(), keyFingerprint: expectedFingerprint } = {}) {
129
+ const cachePath = resolveDeepseekLimitsCachePath({ trackerDir, home });
130
+ let parsed;
131
+ try {
132
+ parsed = JSON.parse(fs.readFileSync(cachePath, "utf8"))?.deepseek;
133
+ } catch (_error) {
134
+ return null;
135
+ }
136
+ const cachedAtMs = Date.parse(parsed?.cached_at || "");
137
+ if (!Number.isFinite(cachedAtMs)) return null;
138
+ if (cachedAtMs > nowMs + 60_000) return null;
139
+ // Pure TTL: balances have no reset instant, so freshness decays with age
140
+ // alone (ark's unknown-reset rule).
141
+ if (nowMs - cachedAtMs > DEEPSEEK_BALANCE_CACHE_TTL_MS) return null;
142
+ if (expectedFingerprint && parsed?.key_fingerprint !== expectedFingerprint) return null;
143
+ const balances = Array.isArray(parsed?.balances)
144
+ ? parsed.balances.filter(
145
+ (entry) =>
146
+ entry &&
147
+ typeof entry.currency === "string" &&
148
+ entry.currency.trim() &&
149
+ balanceNumber(entry.total) !== null,
150
+ )
151
+ : [];
152
+ if (balances.length === 0) return null;
153
+ return {
154
+ configured: true,
155
+ error: null,
156
+ is_available: parsed.is_available === true,
157
+ balances,
158
+ source: "disk-cache",
159
+ stale: true,
160
+ cached_at: parsed.cached_at,
161
+ };
162
+ }
163
+
164
+ function writeDeepseekLimitsCache(limits, { trackerDir, home, nowMs = Date.now(), keyFingerprint: fingerprint } = {}) {
165
+ if (!limits?.configured || limits.error || !Array.isArray(limits.balances) || limits.balances.length === 0) return;
166
+ const cachePath = resolveDeepseekLimitsCachePath({ trackerDir, home });
167
+ const payload = {
168
+ deepseek: {
169
+ is_available: limits.is_available === true,
170
+ balances: limits.balances,
171
+ key_fingerprint: fingerprint || null,
172
+ cached_at: new Date(nowMs).toISOString(),
173
+ },
174
+ };
175
+ try {
176
+ fs.mkdirSync(path.dirname(cachePath), { recursive: true });
177
+ const tmpPath = `${cachePath}.${process.pid}.tmp`;
178
+ fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), { encoding: "utf8", mode: 0o600 });
179
+ fs.renameSync(tmpPath, cachePath);
180
+ } catch (_error) {}
181
+ }
182
+
183
+ /**
184
+ * One live GET /user/balance read. Returns {ok, is_available, balances} on a
185
+ * usable payload, {auth_error: true, error} when the key itself is rejected
186
+ * (actionable — must not be masked by stale cache), {error} otherwise.
187
+ */
188
+ async function fetchDeepseekBalance({ apiKey, fetchImpl, timeoutMs = DEEPSEEK_REQUEST_TIMEOUT_MS } = {}) {
189
+ let response;
190
+ try {
191
+ response = await fetchImpl(DEEPSEEK_BALANCE_URL, {
192
+ method: "GET",
193
+ headers: {
194
+ Authorization: `Bearer ${apiKey}`,
195
+ Accept: "application/json",
196
+ },
197
+ });
198
+ } catch (err) {
199
+ return { error: `DeepSeek balance request failed: ${err?.message || err}` };
200
+ }
201
+ if (response.status === 401 || response.status === 403) {
202
+ return {
203
+ auth_error: true,
204
+ error: `DeepSeek API key was rejected (${response.status}). Check the key in the DeepSeek platform console.`,
205
+ };
206
+ }
207
+ if (!response.ok) {
208
+ return { error: `DeepSeek balance API returned ${response.status}` };
209
+ }
210
+ let body;
211
+ try {
212
+ body = JSON.parse(await response.text());
213
+ } catch (err) {
214
+ return { error: `Could not parse DeepSeek balance response: ${err?.message || err}` };
215
+ }
216
+ try {
217
+ return { ok: true, is_available: body.is_available === true, balances: normalizeDeepseekBalanceResponse(body) };
218
+ } catch (err) {
219
+ return { error: err?.message || "DeepSeek balance response could not be parsed." };
220
+ }
221
+ }
222
+
223
+ /**
224
+ * Fetch the DeepSeek balance card. `persistCache: false` lets the caller
225
+ * suppress the disk write while its aggregate cache generation is stale
226
+ * (a provider-key save mid-fetch must not republish pre-save data, #837).
227
+ */
228
+ async function fetchDeepseekLimits({
229
+ home = os.homedir(),
230
+ trackerDir,
231
+ env = process.env,
232
+ fetchImpl = fetch,
233
+ nowMs = Date.now(),
234
+ timeoutMs = DEEPSEEK_REQUEST_TIMEOUT_MS,
235
+ persistCache = true,
236
+ } = {}) {
237
+ const credential = readDeepseekApiKey({ home, trackerDir, env });
238
+ if (!credential) return { configured: false };
239
+ const fingerprint = keyFingerprint(credential.apiKey);
240
+
241
+ const live = await fetchDeepseekBalance({ apiKey: credential.apiKey, fetchImpl, timeoutMs });
242
+ if (live.ok) {
243
+ const result = {
244
+ configured: true,
245
+ error: null,
246
+ is_available: live.is_available,
247
+ balances: live.balances,
248
+ credential_source: credential.source,
249
+ source: "provider-api",
250
+ stale: false,
251
+ cached_at: new Date(nowMs).toISOString(),
252
+ };
253
+ if (persistCache) {
254
+ writeDeepseekLimitsCache(result, { trackerDir, home, nowMs, keyFingerprint: fingerprint });
255
+ }
256
+ return result;
257
+ }
258
+ if (live.auth_error) {
259
+ return { configured: true, error: live.error, auth_error: true, credential_source: credential.source };
260
+ }
261
+ const cached = readDeepseekLimitsCache({ trackerDir, home, nowMs, keyFingerprint: fingerprint });
262
+ if (cached) return { ...cached, credential_source: credential.source };
263
+ return { configured: true, error: live.error, credential_source: credential.source };
264
+ }
265
+
266
+ module.exports = {
267
+ DEEPSEEK_BALANCE_URL,
268
+ DEEPSEEK_LIMITS_CACHE_FILE,
269
+ DEEPSEEK_ENV_NAME,
270
+ DEEPSEEK_BALANCE_CACHE_TTL_MS,
271
+ balanceNumber,
272
+ fetchDeepseekBalance,
273
+ fetchDeepseekLimits,
274
+ keyFingerprint,
275
+ normalizeDeepseekBalanceResponse,
276
+ readDeepseekApiKey,
277
+ readDeepseekLimitsCache,
278
+ resolveDeepseekLimitsCachePath,
279
+ writeDeepseekLimitsCache,
280
+ };