dsh-grok-subscription 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2.0.1 — 2026-09-29
+
+- Fix **the quota card reporting a raw parser error for an account the upstream API stopped describing with a percentage**. Since the weekly period rolled over on 2026-09-28T16:46Z, `GET /v1/billing?format=credits` answers with a `config` object that carries `isUnifiedBillingUser`, `prepaidBalance`, `onDemandCap`, `onDemandUsed`, `topUpMethod` and the period bounds — and no `creditUsagePercent`, no `productUsage`, and no used/total pair. Every reader in the plugin is unchanged since 1.0.20, so the card simply failed closed with `不可用: Missing creditUsagePercent (keys: config)`, which reads like a broken plugin rather than an upstream shape the plugin does not recognise. Reproduced on a second machine with the same account: same build, same headers, only the clock moved.
+- Name the shape instead of a missing field. The unavailable reading now carries a `code` (`unified-billing` or `missing-percent`) plus the period bounds, the panel renders localized copy for a named code and keeps the raw diagnostic as a hint underneath, and an unnamed failure still shows its own reason.
+- **Show the window even when there is no percentage.** The period start and end come from the same response, so the card now prints `本期窗口: 2026/09/29 00:46:29 → 2026/10/06 00:46:29` whether or not a reading came back. A reset time is never lost to a shape change.
+- Still no invented numbers. A zero prepaid balance and a zero on-demand cap are not a percentage, so the card shows no gauge and the composer badge stays hidden; `parseBillingCredits` is asserted against the captured live body to keep it that way.
+- No adapter, routing, session or RPC-surface changes. `sanitizeUsage` carries the new diagnostic fields through the RPC without exposing anything else.
+
+## 2.0.0 — 2026-09-28
+
 ## 2.0.0 — 2026-09-28
 
 - **Remove the bundled Responses adapter. The `grok-build` route is now always the host's own pi-ai adapter.** The bundled implementation and everything that existed only to support it are gone: its request building, encrypted-reasoning envelope, prompt-cache and usage mapping and image collection (`src/adapter.js` drops from 1081 to 467 lines), the synchronous duck registration, `createGrokBuildAdapterSync` / `createDuckHostAdapter`, the release-then-re-register upgrade 1.2.0 added, and the `DSH_GROK_ADAPTER=fallback` switch. `apply` still returns immediately and builds the adapter from a deferred task, but registers exactly once.

package/README.en.md

@@ -61,13 +61,13 @@ Pick a Grok model your account can use, adjust reasoning effort as needed, and s
 <details>
 <summary>Check the version / pin one / fall back when the UI install fails</summary>
 
-**Settings → Plugins** lists the installed plugins and their versions, and the plugin's own **Settings → Grok Subscription** page shows a version card. To pin a version, put the full `package@version` in the install field, for example `dsh-grok-subscription@2.0.0`.
+**Settings → Plugins** lists the installed plugins and their versions, and the plugin's own **Settings → Grok Subscription** page shows a version card. To pin a version, put the full `package@version` in the install field, for example `dsh-grok-subscription@2.0.1`.
 
 If the UI install fails (an unusual profile directory, say), the equivalent runs against the desktop profile itself (pnpm ≥ 11):
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.1
 ```
 
 `dsh plugin --profile desktop …` is refused: the Electron application owns that profile exclusively. CLI paths, sign-in, and troubleshooting are in the [full user guide](docs/guide.en.md).

package/README.md

@@ -61,13 +61,13 @@
 <details>
 <summary>确认版本 / 固定版本 / 界面安装失败时的兜底</summary>
 
-**设置 → 插件** 会列出已安装插件与版本，插件自己的 **设置 → Grok 订阅** 页也有版本卡片。要固定版本，在安装框里填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.0`。
+**设置 → 插件** 会列出已安装插件与版本，插件自己的 **设置 → Grok 订阅** 页也有版本卡片。要固定版本，在安装框里填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.1`。
 
 界面安装失败时（例如 profile 目录权限异常），可以对桌面版 profile 手动执行等价操作（pnpm ≥ 11）：
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.1
 ```
 
 `dsh plugin --profile desktop …` 会被拒绝：桌面版 profile 由 Electron 应用独占。CLI 路径、登录方式与故障排查见 [完整使用指南](docs/guide.zh-CN.md)。

package/docs/guide.en.md

@@ -8,7 +8,7 @@ For quick setup, see the [README](../README.en.md#install). This guide covers de
 
 You need the DeepSeek Harness desktop app, the official Grok Build CLI, and an account with Grok Build access. The plugin declares Node.js `^22.19.0 || >=24.0.0`; DSH peers use `>=0.1.5-rc.2 <0.3.0-0`, which spans the whole 0.1 and 0.2 lines. See [package.json](../package.json) for the full requirements. Declared compatibility is not a claim that every version has passed live verification.
 
-**Install:** in the desktop app open **Settings → Plugins**, type the package name `dsh-grok-subscription` into the install field, and install it. Then **quit and restart the desktop app completely**; refreshing the page alone does not reload the Host adapter. To pin a version, put the full `package@version` in that field, for example `dsh-grok-subscription@2.0.0`.
+**Install:** in the desktop app open **Settings → Plugins**, type the package name `dsh-grok-subscription` into the install field, and install it. Then **quit and restart the desktop app completely**; refreshing the page alone does not reload the Host adapter. To pin a version, put the full `package@version` in that field, for example `dsh-grok-subscription@2.0.1`.
 
 **The plugin depends on the host's own pi-ai adapter.** From 2.0.0 the `grok-build` route is served entirely by the host's `@deepseek-ai/dsh-llm-pi-ai` / `@earendil-works/pi-ai`, which every DSH installation carries (`@deepseek-ai/dsh` → `dsh-base` → `dsh-llm-pi-ai`, with the `llm-pi-ai` row mounted unconditionally). If those packages cannot be resolved from the DSH installation, the plugin registers no route at all and **Active path** in Settings reads **unavailable**.
 
@@ -16,7 +16,7 @@ If the UI install fails (an unusual profile directory, say), the equivalent runs
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.1
 ```
 
 `dsh plugin --profile desktop …` is refused: the Electron application owns that profile exclusively.
@@ -101,7 +101,7 @@ In the desktop app the `desktop` profile is owned exclusively by the Electron ap
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.1
 ```
 
 Then quit and restart the desktop app completely. After a successful update the profile's `package.json` dependency should show the target version while its `dsh.profile.bundles` entry is unchanged. Refreshing the browser is not enough: without a Host restart the old version keeps loading.

package/docs/guide.zh-CN.md

@@ -8,7 +8,7 @@
 
 需要 DeepSeek Harness 桌面版、官方 Grok Build CLI，以及当前具有 Grok Build 使用资格的订阅账号。插件的 Node.js 要求为 `^22.19.0 || >=24.0.0`，DSH peer 声明以 [package.json](../package.json) 为准；其中 DSH 依赖使用 `>=0.1.5-rc.2 <0.3.0-0`，覆盖 0.1 与 0.2 全线。声明范围不等于所有版本都已经过实机验证。
 
-**安装：** 在桌面版打开 **设置 → 插件**，在安装输入框里填入包名 `dsh-grok-subscription` 并安装，然后**完全退出并重启桌面应用**。仅刷新页面不会重新加载 Host 中的适配器。需要可重复安装时，填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.0`。
+**安装：** 在桌面版打开 **设置 → 插件**，在安装输入框里填入包名 `dsh-grok-subscription` 并安装，然后**完全退出并重启桌面应用**。仅刷新页面不会重新加载 Host 中的适配器。需要可重复安装时，填入完整的 `包名@版本`，例如 `dsh-grok-subscription@2.0.1`。
 
 **插件依赖宿主自带的 pi-ai 适配器。** 从 2.0.0 起，`grok-build` 路由完全由宿主的 `@deepseek-ai/dsh-llm-pi-ai` / `@earendil-works/pi-ai` 服务；DSH 的任何安装方式都带有它们（`@deepseek-ai/dsh` → `dsh-base` → `dsh-llm-pi-ai`，且 `llm-pi-ai` 行无条件挂载）。这两个包无法从 DSH 安装目录解析时，插件不会注册任何路由，设置页的「运行通路」显示**不可用**。
 
@@ -16,7 +16,7 @@
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.1
 ```
 
 `dsh plugin --profile desktop …` 会被直接拒绝：桌面版 profile 由 Electron 应用独占。
@@ -101,7 +101,7 @@ grok-4.6
 
 ```sh
 cd "$HOME/.dsh/profiles/desktop"    # Windows: cd "$env:USERPROFILE\.dsh\profiles\desktop"
-pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.0
+pnpm add --save-exact --config.minimumReleaseAge=0 dsh-grok-subscription@2.0.1
 ```
 
 然后完全退出并重启桌面版。更新成功后该 profile 的 `package.json` 里依赖应变为目标版本，`dsh.profile.bundles` 条目保持不变。仅刷新网页不够：Host 未重启时仍会加载旧版本。

package/lib/client.js

@@ -39,7 +39,7 @@ var import_react2 = require("react");
 var zh = {
   nav: "Grok \u8BA2\u9605",
   title: "Grok \u8BA2\u9605",
-  subtitle: "\u7528 SuperGrok / X Premium\uFF08Grok Build\uFF09\u4F1A\u8BDD\uFF0C\u800C\u4E0D\u662F XAI_API_KEY\u3002\xB7 2.0.0",
+  subtitle: "\u7528 SuperGrok / X Premium\uFF08Grok Build\uFF09\u4F1A\u8BDD\uFF0C\u800C\u4E0D\u662F XAI_API_KEY\u3002\xB7 2.0.1",
   signedIn: "\u5DF2\u767B\u5F55",
   signedOut: "\u672A\u767B\u5F55",
   account: "\u8D26\u6237",
@@ -86,6 +86,9 @@ var zh = {
   usageUsed: "\u5DF2\u7528",
   usageRemaining: "\u5269\u4F59\u7EA6",
   usageReset: "\u5468\u671F\u7ED3\u675F / \u91CD\u7F6E",
+  usageWindow: "\u672C\u671F\u7A97\u53E3",
+  usageUnifiedBilling: "\u4E0A\u6E38\u672A\u8FD4\u56DE\u989D\u5EA6\u767E\u5206\u6BD4\uFF1A\u8BE5\u8D26\u53F7\u5DF2\u662F\u7EDF\u4E00\u8BA1\u8D39\u5F62\u6001\uFF08\u4EE5\u9884\u4ED8\u4F59\u989D\u4E0E\u6309\u91CF\u4E0A\u9650\u8BA1\u91CF\uFF09\uFF0C\u56E0\u6B64\u6CA1\u6709\u53EF\u5C55\u793A\u7684\u5468\u989D\u5EA6\u8BFB\u6570\u3002",
+  usageMissingPercent: "\u4E0A\u6E38\u672A\u8FD4\u56DE\u989D\u5EA6\u767E\u5206\u6BD4\uFF0C\u672C\u671F\u6682\u65E0\u53EF\u7528\u8BFB\u6570\u3002",
   usageUnavailable: "\u4E0D\u53EF\u7528",
   usageRefresh: "\u5237\u65B0\u7528\u91CF",
   usageOpenGrok: "\u5728 grok.com \u67E5\u770B\u7528\u91CF",
@@ -120,7 +123,7 @@ var zh = {
 var en = {
   nav: "Grok Subscription",
   title: "Grok Subscription",
-  subtitle: "Use a SuperGrok / X Premium (Grok Build) session, not XAI_API_KEY. \xB7 2.0.0",
+  subtitle: "Use a SuperGrok / X Premium (Grok Build) session, not XAI_API_KEY. \xB7 2.0.1",
   signedIn: "Signed in",
   signedOut: "Signed out",
   account: "Account",
@@ -167,6 +170,9 @@ var en = {
   usageUsed: "Used",
   usageRemaining: "Remaining \u2248",
   usageReset: "Period end / reset",
+  usageWindow: "Current window",
+  usageUnifiedBilling: "The upstream API returned no credit percentage: this account is on unified billing (measured by prepaid balance and an on-demand cap), so there is no weekly credit reading to show.",
+  usageMissingPercent: "The upstream API returned no credit percentage for this period.",
   usageUnavailable: "Unavailable",
   usageRefresh: "Refresh usage",
   usageOpenGrok: "View usage on grok.com",
@@ -830,6 +836,7 @@ function VersionCard({ call, t }) {
     ] }) : null
   ] });
 }
+var EXPLAINED_USAGE_CODES = /* @__PURE__ */ new Set(["unified-billing", "missing-percent"]);
 function UsagePanel({ usage, t, usageBusy, onRefresh, signedIn }) {
   const ok = usage?.status === "ok";
   const usedNumber = ok && Number.isFinite(usage.usedPercent) ? usage.usedPercent : void 0;
@@ -867,9 +874,16 @@ function UsagePanel({ usage, t, usageBusy, onRefresh, signedIn }) {
         ] }) : null,
         usage.periodEnd && usage.periodEndLocal ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("code", { children: usage.periodEnd }) : null
       ] })
-    ] }) : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("p", { className: "gsEmpty", children: [
-      t("usageUnavailable"),
-      usage?.reason ? `: ${usage.reason}` : ""
+    ] }) : /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "gsEmpty", children: [
+      /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { children: EXPLAINED_USAGE_CODES.has(usage?.code) ? t(usage.code === "unified-billing" ? "usageUnifiedBilling" : "usageMissingPercent") : `${t("usageUnavailable")}${usage?.reason ? `: ${usage.reason}` : ""}` }),
+      usage?.periodStartLocal || usage?.periodEndLocal ? /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("p", { className: "gsHint", children: [
+        t("usageWindow"),
+        ": ",
+        usage?.periodStartLocal ?? usage?.periodStart ?? "\u2014",
+        " \u2192 ",
+        usage?.periodEndLocal ?? usage?.periodEnd ?? "\u2014"
+      ] }) : null,
+      EXPLAINED_USAGE_CODES.has(usage?.code) && usage?.reason ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("p", { className: "gsHint", children: /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("code", { children: usage.reason }) }) : null
     ] }),
     products.length > 0 ? /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("div", { className: "gsRows", children: products.map((row, index) => /* @__PURE__ */ (0, import_jsx_runtime2.jsxs)("div", { className: "gsRow", children: [
       /* @__PURE__ */ (0, import_jsx_runtime2.jsx)("span", { children: row.name ?? "\u2014" }),

package/lib/index.js

@@ -457,10 +457,11 @@ async function loadCatalog(accessToken, options = {}) {
 // src/usage.js
 var USAGE_SOURCE = "billing-credits-undocumented";
 var SHANGHAI_TZ = "Asia/Shanghai";
-function unavailable(reason) {
+function unavailable(reason, extra = {}) {
   return Object.freeze({
     status: "unavailable",
     reason: typeof reason === "string" && reason.trim() ? reason.trim() : "Usage unavailable",
+    ...extra,
     experimental: true,
     source: USAGE_SOURCE
   });
@@ -516,6 +517,23 @@ function missingPercentReason(body) {
   }
   return `Missing creditUsagePercent (keys: ${keys.join(",")})`;
 }
+function isUnifiedBillingBody(body) {
+  const config = isPlainObject(body.config) ? body.config : void 0;
+  return config?.isUnifiedBillingUser === true || isPlainObject(config?.onDemandCap) || isPlainObject(config?.prepaidBalance);
+}
+function unifiedBillingReason(body) {
+  const config = isPlainObject(body.config) ? body.config : {};
+  const balance = asFiniteNumber(config.prepaidBalance);
+  const cap = asFiniteNumber(config.onDemandCap);
+  return `No credit percentage in this billing response (unified billing: prepaidBalance ${balance ?? "n/a"}, onDemandCap ${cap ?? "n/a"})`;
+}
+function periodFields(body) {
+  const { start, end } = resolvePeriodBounds(body);
+  return {
+    ...start ? { periodStart: start, periodStartLocal: formatShanghai(start) } : {},
+    ...end ? { periodEnd: end, periodEndLocal: formatShanghai(end) } : {}
+  };
+}
 function firstDefined(...values) {
   for (const value of values) {
     if (value !== void 0 && value !== null) return value;
@@ -629,7 +647,14 @@ function parseBillingCredits(body) {
   }
   const usedPercent = resolveUsedPercent(body);
   if (usedPercent === void 0) {
-    return unavailable(missingPercentReason(body));
+    const unified = isUnifiedBillingBody(body);
+    return unavailable(
+      unified ? unifiedBillingReason(body) : missingPercentReason(body),
+      {
+        code: unified ? "unified-billing" : "missing-percent",
+        ...periodFields(body)
+      }
+    );
   }
   const { start: periodStart, end: periodEnd } = resolvePeriodBounds(body);
   const productUsage = sanitizeProductUsage(resolveProductUsage(body));
@@ -1936,6 +1961,10 @@ function sanitizeUsage(usage) {
   };
   if (out.status !== "ok") {
     out.reason = typeof usage.reason === "string" ? usage.reason : "Usage unavailable";
+    if (typeof usage.code === "string") out.code = usage.code;
+    for (const field of ["periodStart", "periodStartLocal", "periodEnd", "periodEndLocal"]) {
+      if (typeof usage[field] === "string") out[field] = usage[field];
+    }
     return out;
   }
   if (typeof usage.usedPercent === "number" && Number.isFinite(usage.usedPercent)) out.usedPercent = usage.usedPercent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-grok-subscription",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Use a SuperGrok or X Premium Grok Build subscription in DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",