@juanbenjumea/pi-provider-usage-fetcher 0.3.3 → 0.3.5

package/README.md

@@ -16,12 +16,15 @@ Despite the name (historical), this package covers more than OpenCode Go:
 | **Kimi Coding** | `KIMI_API_KEY`, `auth.json`, explicit apiKey | `GET https://api.kimi.com/coding/v1/usages` |
 | **Synthetic** | `SYNTHETIC_API_KEY`, `auth.json`, explicit apiKey | `GET https://api.synthetic.new/v2/quotas` |
 | **z.ai / GLM** | Region-specific environment key, `auth.json`, explicit apiKey | `GET {api.z.ai or open.bigmodel.cn}/api/monitor/usage/quota/limit` |
+| **Grok / SuperGrok** | `GROK_OAUTH_TOKEN`, `GROK_ACCESS_TOKEN`, `auth.json` (`grok`), or `~/.grok/auth.json` | Grok CLI billing proxy (`cli-chat-proxy.grok.com/v1/billing?format=credits`) |
 | **Cursor** | `quota-sessions.json`, env, CodexBar, Cursor app DB | `cursor.com/api/usage-summary` |
 | **CommandCode** | `quota-sessions.json`, env, CodexBar | `api.commandcode.ai/internal/billing/*` |
 | **Openference** | API key from caller, `OPENFERENCE_API_KEY`, or `auth.json` | `GET https://openference.com/api/user/me` |
 
 Legacy OpenCode Go dashboard cookie scraping remains as a fallback when no API key is configured.
 
+Grok reports **subscription credits**, not xAI API spend. Its quota adapter follows the Grok CLI billing route observed in CodexBar; this is a private CLI endpoint and may change. It does not use xAI inference API keys or xAI Management API spend endpoints.
+
 ## Install
 
 ```bash

package/dist/index.d.ts

@@ -21,4 +21,5 @@ export * from "./lib/gemini/gemini.ts";
 export * from "./lib/kimi/kimi.ts";
 export * from "./lib/synthetic/synthetic.ts";
 export * from "./lib/zai/zai.ts";
+export * from "./lib/grok/grok.ts";
 export * from "./lib/provider/dispatch.ts";

package/dist/index.js

@@ -21,4 +21,5 @@ export * from "./lib/gemini/gemini.js";
 export * from "./lib/kimi/kimi.js";
 export * from "./lib/synthetic/synthetic.js";
 export * from "./lib/zai/zai.js";
+export * from "./lib/grok/grok.js";
 export * from "./lib/provider/dispatch.js";

package/dist/lib/grok/grok.d.ts

@@ -0,0 +1,5 @@
+import type { QuotaFetchOptions, QuotaSnapshot } from "../shared/quota-types.ts";
+export declare const GROK_CREDITS_ENDPOINT = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+/** Parse the scope-keyed auth.json written by `grok login`, preferring SuperGrok OIDC. */
+export declare function parseGrokAuthFile(contents: string): string | undefined;
+export declare function fetchGrokUsage(options?: QuotaFetchOptions): Promise<QuotaSnapshot>;

package/dist/lib/grok/grok.js

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { authCredential, resolveAuthValue } from "../auth/auth.js";
+import { clampPercent, formatResetTime, safeError } from "../shared/format.js";
+import { fetchJson } from "../shared/http.js";
+export const GROK_CREDITS_ENDPOINT = "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
+const OIDC_SCOPE_PREFIX = "https://auth.x.ai::";
+const LEGACY_SCOPE = "https://accounts.x.ai/sign-in";
+/** Parse the scope-keyed auth.json written by `grok login`, preferring SuperGrok OIDC. */
+export function parseGrokAuthFile(contents) {
+    try {
+        const parsed = JSON.parse(contents);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return undefined;
+        const entries = Object.entries(parsed).filter((entry) => !!entry[1] && typeof entry[1] === "object" && !Array.isArray(entry[1]));
+        const candidates = [
+            ...entries.filter(([scope]) => scope.startsWith(OIDC_SCOPE_PREFIX)),
+            ...entries.filter(([scope]) => scope === LEGACY_SCOPE || scope.includes("/sign-in")),
+        ];
+        for (const [, entry] of candidates) {
+            const token = typeof entry.key === "string" ? normalizeBearer(entry.key) : undefined;
+            if (token)
+                return token;
+        }
+    }
+    catch {
+        // Treat absent, malformed, or partial CLI credentials as unavailable.
+    }
+    return undefined;
+}
+function normalizeBearer(value) {
+    let token = value?.trim() ?? "";
+    if (token.toLowerCase().startsWith("bearer "))
+        token = token.slice(7).trim();
+    // xAI inference keys and cookies are not SuperGrok OAuth credentials.
+    if (!token ||
+        token.toLowerCase().startsWith("xai-") ||
+        token.toLowerCase().startsWith("cookie:") ||
+        token.includes("=")) {
+        return undefined;
+    }
+    return token;
+}
+function grokCliToken() {
+    const configuredHome = process.env.GROK_HOME?.trim();
+    const home = configuredHome
+        ? resolve(configuredHome.replace(/^~(?=\/|$)/, homedir()))
+        : join(homedir(), ".grok");
+    const path = join(home, "auth.json");
+    try {
+        if (existsSync(path))
+            return parseGrokAuthFile(readFileSync(path, "utf8"));
+    }
+    catch {
+        // Treat inaccessible credentials as unavailable; never expose file errors or contents.
+    }
+    return undefined;
+}
+function grokToken(apiKey) {
+    return (normalizeBearer(apiKey) ||
+        normalizeBearer(resolveAuthValue(process.env.GROK_OAUTH_TOKEN)) ||
+        normalizeBearer(resolveAuthValue(process.env.GROK_ACCESS_TOKEN)) ||
+        normalizeBearer(authCredential("grok", "supergrok")) ||
+        grokCliToken());
+}
+function finiteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function parseDate(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const date = new Date(value);
+    return Number.isFinite(date.getTime()) ? date : undefined;
+}
+function windowLabel(start, end) {
+    if (!start || !end || end <= start)
+        return "Credits";
+    const days = (end.getTime() - start.getTime()) / 86_400_000;
+    if (days >= 4 && days <= 12)
+        return "Week";
+    if (days >= 20 && days <= 45)
+        return "Month";
+    return "Credits";
+}
+export async function fetchGrokUsage(options = {}) {
+    const token = grokToken(options.apiKey);
+    if (!token)
+        return { provider: "Grok", windows: [], error: "no-auth", fetchedAt: Date.now() };
+    try {
+        const { data } = await fetchJson(GROK_CREDITS_ENDPOINT, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "x-xai-token-auth": "xai-grok-cli",
+                Accept: "application/json",
+            },
+        }, options.timeoutMs ?? 10_000, options.fetchImpl ?? fetch);
+        const config = data?.config;
+        if (!config || typeof config !== "object")
+            throw new Error("invalid-response");
+        const creditPercent = finiteNumber(config.creditUsagePercent);
+        const cap = finiteNumber(config.onDemandCap?.val);
+        const used = finiteNumber(config.onDemandUsed?.val);
+        const derivedPercent = cap !== undefined && cap > 0 && used !== undefined ? (used / cap) * 100 : undefined;
+        const usedPercent = creditPercent ?? derivedPercent;
+        if (usedPercent === undefined)
+            throw new Error("invalid-response");
+        const period = config.currentPeriod;
+        const currentPeriodEnd = parseDate(period?.end);
+        const end = currentPeriodEnd ?? parseDate(config.billingPeriodEnd);
+        // Do not combine a start from the current-period object with a fallback end
+        // from another period; duration is used only to label the quota window.
+        const start = currentPeriodEnd
+            ? parseDate(period?.start)
+            : parseDate(config.billingPeriodStart);
+        const resetDate = end && end.getTime() > Date.now() ? end : undefined;
+        const window = {
+            label: windowLabel(start, end),
+            usedPercent: clampPercent(usedPercent),
+            ...(resetDate
+                ? { resetsAt: resetDate.toISOString(), resetsIn: formatResetTime(resetDate) }
+                : {}),
+        };
+        return { provider: "Grok", windows: [window], fetchedAt: Date.now() };
+    }
+    catch (error) {
+        return { provider: "Grok", windows: [], error: safeError(error), fetchedAt: Date.now() };
+    }
+}

package/dist/lib/provider/dispatch.js

@@ -7,6 +7,7 @@ import { fetchGeminiUsage } from "../gemini/gemini.js";
 import { fetchKimiUsage } from "../kimi/kimi.js";
 import { fetchSyntheticUsage } from "../synthetic/synthetic.js";
 import { fetchZaiUsage } from "../zai/zai.js";
+import { fetchGrokUsage } from "../grok/grok.js";
 import { fetchCursorUsage } from "../cursor/cursor.js";
 import { fetchCommandCodeUsage } from "../commandcode/commandcode.js";
 import { fetchOpenferenceUsage } from "../openference/openference.js";
@@ -34,6 +35,9 @@ export const PROVIDER_MAP = {
     zai: "zai",
     "z.ai": "zai",
     "glm-coding-plan": "zai",
+    grok: "grok",
+    supergrok: "grok",
+    "grok-cli": "grok",
     cursor: "cursor",
     commandcode: "commandcode",
     openference: "openference",
@@ -55,6 +59,7 @@ export const PROVIDER_FETCHERS = {
     kimi: (options) => fetchKimiUsage(options),
     synthetic: fetchSyntheticUsage,
     zai: fetchZaiUsage,
+    grok: fetchGrokUsage,
     cursor: () => fetchCursorUsage(),
     commandcode: () => fetchCommandCodeUsage(),
     openference: (options) => fetchOpenferenceUsage(options?.apiKey, options),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@juanbenjumea/pi-provider-usage-fetcher",
-  "version": "0.3.3",
-  "description": "Multi-provider usage fetchers for coding assistant subscriptions, including OpenCode Go, Claude, Codex, Cursor, Copilot, Gemini, Kimi, and more.",
+  "version": "0.3.5",
+  "description": "Multi-provider usage fetchers for coding assistant subscriptions, including OpenCode Go, Claude, Codex, Grok, Cursor, Copilot, Gemini, Kimi, and more.",
   "type": "module",
   "license": "MIT",
   "author": "Juan Benjumea",
@@ -55,7 +55,8 @@
     "./gemini.ts": "./dist/lib/gemini/gemini.js",
     "./kimi.ts": "./dist/lib/kimi/kimi.js",
     "./synthetic.ts": "./dist/lib/synthetic/synthetic.js",
-    "./zai.ts": "./dist/lib/zai/zai.js"
+    "./zai.ts": "./dist/lib/zai/zai.js",
+    "./grok.ts": "./dist/lib/grok/grok.js"
   },
   "files": [
     "dist/",