@cartanova/qgrid-cli 2.10.10 → 2.11.0

package/bundle/src/utils/providers/grok/grok-quota.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "vitest";
+
+import { readGrokBilling, readGrokSettings, readGrokSubscription } from "./grok-quota";
+
+const credentials = {
+  accessToken: "header.payload.sig",
+  userId: "19bfa1b2-a163-9e0c-8de1-832a73e2695e",
+};
+
+function fetchReturning(
+  body: unknown,
+  status = 200,
+  seen?: Array<{ url: string; headers: Headers }>,
+): typeof fetch {
+  return async (input, init) => {
+    seen?.push({ url: String(input), headers: new Headers(init?.headers) });
+    return new Response(typeof body === "string" ? body : JSON.stringify(body), { status });
+  };
+}
+
+describe("readGrokBilling", () => {
+  it("maps the camelCase credits schema to the shared quota shape", async () => {
+    const seen: Array<{ url: string; headers: Headers }> = [];
+    const result = await readGrokBilling(credentials, {
+      fetch: fetchReturning(
+        {
+          config: {
+            currentPeriod: {
+              type: "USAGE_PERIOD_TYPE_WEEKLY",
+              start: "2026-10-12T00:00:00Z",
+              end: "2026-10-19T00:00:00Z",
+            },
+            creditUsagePercent: 42,
+            productUsage: [{ product: "GrokBot", usagePercent: 42 }],
+            isUnifiedBillingUser: true,
+            prepaidBalance: { val: "0" },
+          },
+        },
+        200,
+        seen,
+      ),
+    });
+    expect(seen[0]?.url).toBe("https://cli-chat-proxy.grok.com/v1/billing?format=credits");
+    expect(seen[0]?.headers.get("x-userid")).toBe(credentials.userId);
+    expect(seen[0]?.headers.get("x-xai-token-auth")).toBe("xai-grok-cli");
+    expect(result).toMatchObject({
+      kind: "ok",
+      utilizationPct: 42,
+      windowDurationMins: 7 * 24 * 60,
+      resetsAt: Date.parse("2026-10-19T00:00:00Z") / 1000,
+      limitId: "USAGE_PERIOD_TYPE_WEEKLY",
+      periodType: "USAGE_PERIOD_TYPE_WEEKLY",
+      periodEnd: "2026-10-19T00:00:00Z",
+      periodEndMs: Date.parse("2026-10-19T00:00:00Z"),
+      prepaidBalance: 0,
+    });
+  });
+
+  it("returns lookup_failed on HTTP errors and unexpected shapes", async () => {
+    expect(await readGrokBilling(credentials, { fetch: fetchReturning("nope", 500) })).toMatchObject({
+      kind: "lookup_failed",
+    });
+    expect(
+      await readGrokBilling(credentials, { fetch: fetchReturning({ credit_usage_percent: 3 }) }),
+    ).toMatchObject({ kind: "lookup_failed" });
+    expect(
+      await readGrokBilling(credentials, {
+        fetch: async () => {
+          throw new TypeError("offline");
+        },
+      }),
+    ).toMatchObject({ kind: "lookup_failed" });
+  });
+});
+
+describe("readGrokSettings", () => {
+  it("reads on_demand_enabled and the gate fields", async () => {
+    const result = await readGrokSettings(credentials, {
+      fetch: fetchReturning({
+        min_client_version: "1.0.13",
+        force_update: true,
+        default_model: "grok-4.7",
+        subscription_tier_display: "SuperGrok Plus",
+        on_demand_enabled: null,
+        image_gen_enabled: true,
+        video_gen_enabled: true,
+        voice_mode_enabled: true,
+      }),
+    });
+    expect(result).toEqual({
+      kind: "ok",
+      onDemandEnabled: null,
+      minClientVersion: "1.0.13",
+      defaultModel: "grok-4.7",
+      subscriptionTierDisplay: "SuperGrok Plus",
+      imageGenEnabled: true,
+      videoGenEnabled: true,
+      voiceModeEnabled: true,
+    });
+  });
+
+  it("treats an absent on_demand_enabled as null and true as true", async () => {
+    expect(await readGrokSettings(credentials, { fetch: fetchReturning({}) })).toMatchObject({
+      onDemandEnabled: null,
+    });
+    expect(
+      await readGrokSettings(credentials, { fetch: fetchReturning({ on_demand_enabled: true }) }),
+    ).toMatchObject({ onDemandEnabled: true });
+  });
+});
+
+describe("readGrokSubscription", () => {
+  it("returns the tier", async () => {
+    const seen: Array<{ url: string; headers: Headers }> = [];
+    const result = await readGrokSubscription(credentials, {
+      fetch: fetchReturning(
+        { userId: credentials.userId, subscriptionTier: "SuperGrokPlus", hasGrokCodeAccess: true },
+        200,
+        seen,
+      ),
+    });
+    expect(seen[0]?.url).toBe("https://cli-chat-proxy.grok.com/v1/user?include=subscription");
+    expect(result).toEqual({
+      kind: "ok",
+      userId: credentials.userId,
+      tier: "SuperGrokPlus",
+      hasGrokCodeAccess: true,
+      dataRetentionOptOut: null,
+    });
+  });
+
+  it("returns codingDataRetentionOptOut", async () => {
+    const result = await readGrokSubscription(credentials, {
+      fetch: fetchReturning({ userId: credentials.userId, codingDataRetentionOptOut: true }),
+    });
+    expect(result).toMatchObject({ kind: "ok", dataRetentionOptOut: true });
+    const off = await readGrokSubscription(credentials, {
+      fetch: fetchReturning({ userId: credentials.userId, codingDataRetentionOptOut: false }),
+    });
+    expect(off).toMatchObject({ kind: "ok", dataRetentionOptOut: false });
+  });
+});

package/bundle/src/utils/providers/grok/grok-quota.ts

@@ -0,0 +1,198 @@
+import { grokProxyGet } from "./grok-direct-client";
+import { buildGrokProxyGetHeaders } from "./grok-headers";
+import {
+  GrokBillingConfig,
+  GrokSettings,
+  GrokUserSubscription,
+  type GrokCredentials,
+} from "./grok-types";
+
+// Chat-proxy reads for the quota gate (§5.3). Every reader returns a result union and never
+// throws, so callers can fail open. The `ok` billing shape carries the same fields as
+// OpenAIQuotaUsageResult so usage views can treat both providers alike.
+
+export interface GrokProxyReadOptions {
+  fetch?: typeof fetch;
+  signal?: AbortSignal;
+  baseUrl?: string;
+  now?: () => number;
+}
+
+type ProxyCredentials = Pick<GrokCredentials, "accessToken" | "userId">;
+
+export type GrokQuotaUsageResult =
+  | {
+      kind: "ok";
+      // Same names as OpenAIQuotaUsageResult.
+      utilizationPct: number;
+      cacheAgeMs: number;
+      windowDurationMins: number | null;
+      /** Unix seconds, like the OpenAI wham `resetsAt`. */
+      resetsAt: number | null;
+      limitId: string | null;
+      // Grok specifics.
+      periodType: string;
+      periodStart: string;
+      periodEnd: string;
+      /** Epoch ms of periodEnd, or null when the timestamp is unparseable. */
+      periodEndMs: number | null;
+      prepaidBalance: number | null;
+      raw: GrokBillingConfig;
+    }
+  | { kind: "lookup_failed"; reason: string };
+
+function reasonOf(cause: unknown): string {
+  return cause instanceof Error ? cause.message : String(cause);
+}
+
+function proxyHeaders(credentials: ProxyCredentials): Record<string, string> {
+  return buildGrokProxyGetHeaders({ bearer: credentials.accessToken, userId: credentials.userId });
+}
+
+function numberOrNull(value: number | string | undefined): number | null {
+  if (value === undefined) return null;
+  // Number() returns a number argument unchanged and parses a numeric string.
+  const parsed = Number(value);
+
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/** `GET {proxy}/billing?format=credits` (camelCase; U0 item 3). */
+export async function readGrokBilling(
+  credentials: ProxyCredentials,
+  options: GrokProxyReadOptions = {},
+): Promise<GrokQuotaUsageResult> {
+  try {
+    const { json } = await grokProxyGet("/billing?format=credits", {
+      headers: proxyHeaders(credentials),
+      ...options,
+    });
+
+    const parsed = GrokBillingConfig.safeParse(json);
+
+    if (!parsed.success) {
+      return { kind: "lookup_failed", reason: `unexpected billing shape: ${parsed.error.message}` };
+    }
+
+    const config = parsed.data.config;
+
+    if (!Number.isFinite(config.creditUsagePercent)) {
+      return { kind: "lookup_failed", reason: "creditUsagePercent unavailable" };
+    }
+
+    const start = Date.parse(config.currentPeriod.start);
+    const end = Date.parse(config.currentPeriod.end);
+    const endMs = Number.isNaN(end) ? null : end;
+
+    return {
+      kind: "ok",
+      utilizationPct: config.creditUsagePercent,
+      cacheAgeMs: 0,
+      windowDurationMins:
+        endMs !== null && !Number.isNaN(start) && endMs > start
+          ? Math.round((endMs - start) / 60_000)
+          : null,
+      resetsAt: endMs === null ? null : Math.floor(endMs / 1000),
+      limitId: config.currentPeriod.type,
+      periodType: config.currentPeriod.type,
+      periodStart: config.currentPeriod.start,
+      periodEnd: config.currentPeriod.end,
+      periodEndMs: endMs,
+      prepaidBalance: numberOrNull(config.prepaidBalance?.val),
+      raw: parsed.data,
+    };
+  } catch (error) {
+    return { kind: "lookup_failed", reason: reasonOf(error) };
+  }
+}
+
+export type GrokSettingsResult =
+  | {
+      kind: "ok";
+      /** D6: `true` excludes the token; null/false/absent allows it. */
+      onDemandEnabled: boolean | null;
+      minClientVersion: string | null;
+      defaultModel: string | null;
+      subscriptionTierDisplay: string | null;
+      imageGenEnabled: boolean | null;
+      videoGenEnabled: boolean | null;
+      voiceModeEnabled: boolean | null;
+    }
+  | { kind: "lookup_failed"; reason: string };
+
+/** `GET {proxy}/settings`. */
+export async function readGrokSettings(
+  credentials: ProxyCredentials,
+  options: GrokProxyReadOptions = {},
+): Promise<GrokSettingsResult> {
+  try {
+    const { json } = await grokProxyGet("/settings", {
+      headers: proxyHeaders(credentials),
+      ...options,
+    });
+
+    const parsed = GrokSettings.safeParse(json);
+
+    if (!parsed.success) {
+      return {
+        kind: "lookup_failed",
+        reason: `unexpected settings shape: ${parsed.error.message}`,
+      };
+    }
+
+    const settings = parsed.data;
+
+    return {
+      kind: "ok",
+      onDemandEnabled: settings.on_demand_enabled ?? null,
+      minClientVersion: settings.min_client_version ?? null,
+      defaultModel: settings.default_model ?? null,
+      subscriptionTierDisplay: settings.subscription_tier_display ?? null,
+      imageGenEnabled: settings.image_gen_enabled ?? null,
+      videoGenEnabled: settings.video_gen_enabled ?? null,
+      voiceModeEnabled: settings.voice_mode_enabled ?? null,
+    };
+  } catch (error) {
+    return { kind: "lookup_failed", reason: reasonOf(error) };
+  }
+}
+
+export type GrokSubscriptionResult =
+  | {
+      kind: "ok";
+      userId: string;
+      tier: string | null;
+      hasGrokCodeAccess: boolean | null;
+      /** `codingDataRetentionOptOut`: true means Zero Data Retention is on; null when absent. */
+      dataRetentionOptOut: boolean | null;
+    }
+  | { kind: "lookup_failed"; reason: string };
+
+/** `GET {proxy}/user?include=subscription`. */
+export async function readGrokSubscription(
+  credentials: ProxyCredentials,
+  options: GrokProxyReadOptions = {},
+): Promise<GrokSubscriptionResult> {
+  try {
+    const { json } = await grokProxyGet("/user?include=subscription", {
+      headers: proxyHeaders(credentials),
+      ...options,
+    });
+
+    const parsed = GrokUserSubscription.safeParse(json);
+
+    if (!parsed.success) {
+      return { kind: "lookup_failed", reason: `unexpected user shape: ${parsed.error.message}` };
+    }
+
+    return {
+      kind: "ok",
+      userId: parsed.data.userId,
+      tier: parsed.data.subscriptionTier ?? null,
+      hasGrokCodeAccess: parsed.data.hasGrokCodeAccess ?? null,
+      dataRetentionOptOut: parsed.data.codingDataRetentionOptOut ?? null,
+    };
+  } catch (error) {
+    return { kind: "lookup_failed", reason: reasonOf(error) };
+  }
+}

package/bundle/src/utils/providers/grok/grok-refresh.test.ts

@@ -0,0 +1,239 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { GROK_OAUTH_CLIENT_ID } from "./grok-constants";
+import { resetGrokDiscoveryCache } from "./grok-oauth";
+import {
+  GROK_REFRESH_MARGIN_MS,
+  GrokReauthRequiredError,
+  GrokRefreshCoordinator,
+  GrokRefreshTransientError,
+  grokNeedsRefresh,
+  grokRefreshJitterMs,
+} from "./grok-refresh";
+import type { GrokCredentials } from "./grok-types";
+
+const USER_ID = "11111111-2222-3333-4444-555555555555";
+
+function accessToken(tag: string): string {
+  const header = Buffer.from(JSON.stringify({ typ: "at+jwt", alg: "ES256" })).toString("base64url");
+  const payload = Buffer.from(
+    JSON.stringify({ iss: "https://auth.x.ai", sub: USER_ID, jti: tag }),
+  ).toString("base64url");
+  return `${header}.${payload}.c2ln`;
+}
+
+function credentials(overrides: Partial<GrokCredentials> = {}): GrokCredentials {
+  return {
+    authMode: "oauth",
+    accessToken: accessToken("old"),
+    refreshToken: "rt-old",
+    expiresAt: "2026-10-16T06:00:00.000Z",
+    issuer: "https://auth.x.ai",
+    clientId: GROK_OAUTH_CLIENT_ID,
+    scopes: ["openid"],
+    userId: USER_ID,
+    sessionId: "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
+    agentId: "ffffffff-bbbb-cccc-dddd-eeeeeeeeeeee",
+    ...overrides,
+  };
+}
+
+const json = (status: number, body: unknown): Response =>
+  new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+
+const NOW = Date.parse("2026-10-16T05:00:00Z");
+
+function tokenFetch(reply: () => Response | Promise<Response>): {
+  fetch: typeof fetch;
+  bodies: URLSearchParams[];
+} {
+  const bodies: URLSearchParams[] = [];
+  const impl = async (input: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    if (url.endsWith("/.well-known/openid-configuration"))
+      return json(200, {
+        authorization_endpoint: "https://auth.x.ai/oauth2/auth",
+        token_endpoint: "https://auth.x.ai/oauth2/token",
+      });
+    if (url !== "https://auth.x.ai/oauth2/token") throw new TypeError(`unexpected ${url}`);
+    bodies.push(new URLSearchParams(init?.body instanceof URLSearchParams ? init.body : ""));
+    return reply();
+  };
+  return { fetch: impl, bodies };
+}
+
+beforeEach(() => resetGrokDiscoveryCache());
+afterEach(() => resetGrokDiscoveryCache());
+
+describe("refresh timing", () => {
+  it("is stable per account and bounded to 0..60 s", () => {
+    const jitter = grokRefreshJitterMs(USER_ID);
+    expect(grokRefreshJitterMs(USER_ID)).toBe(jitter);
+    expect(jitter).toBeGreaterThanOrEqual(0);
+    expect(jitter).toBeLessThanOrEqual(60_000);
+  });
+
+  it("flips exactly at expiresAt - 300 s - jitter", () => {
+    const creds = credentials();
+    const boundary =
+      Date.parse(creds.expiresAt) - GROK_REFRESH_MARGIN_MS - grokRefreshJitterMs(USER_ID);
+    expect(grokNeedsRefresh(creds, boundary - 1)).toBe(false);
+    expect(grokNeedsRefresh(creds, boundary)).toBe(true);
+    expect(new GrokRefreshCoordinator().needsRefresh(creds, boundary + 1)).toBe(true);
+  });
+});
+
+describe("GrokRefreshCoordinator.refresh", () => {
+  it("keeps the old refresh token when not rotated and persists before resolving", async () => {
+    const { fetch, bodies } = tokenFetch(() =>
+      json(200, { access_token: accessToken("new"), expires_in: 21_600 }),
+    );
+    const persisted: GrokCredentials[] = [];
+    const coordinator = new GrokRefreshCoordinator({ fetch, now: () => NOW });
+    const next = await coordinator.refresh(7, credentials(), async (value) => {
+      persisted.push(value);
+    });
+
+    expect(Object.fromEntries(bodies[0] ?? [])).toEqual({
+      grant_type: "refresh_token",
+      refresh_token: "rt-old",
+      client_id: GROK_OAUTH_CLIENT_ID,
+    });
+    expect(next.refreshToken).toBe("rt-old");
+    expect(next.accessToken).toBe(accessToken("new"));
+    expect(next.expiresAt).toBe(new Date(NOW + 21_600_000).toISOString());
+    expect(next.sessionId).toBe(credentials().sessionId);
+    expect(persisted).toEqual([next]);
+  });
+
+  it("stores a rotated refresh token", async () => {
+    const { fetch } = tokenFetch(() =>
+      json(200, { access_token: accessToken("new"), refresh_token: "rt-new", expires_in: 60 }),
+    );
+    const next = await new GrokRefreshCoordinator({ fetch, now: () => NOW }).refresh(
+      7,
+      credentials(),
+      async () => undefined,
+    );
+    expect(next.refreshToken).toBe("rt-new");
+  });
+
+  it("classifies invalid_grant/invalid_client as terminal and 503/network as transient", async () => {
+    for (const error of ["invalid_grant", "invalid_client"]) {
+      const { fetch } = tokenFetch(() => json(400, { error }));
+      await expect(
+        new GrokRefreshCoordinator({ fetch }).refresh(1, credentials(), async () => undefined),
+      ).rejects.toBeInstanceOf(GrokReauthRequiredError);
+    }
+    const unavailable = tokenFetch(() => json(503, { error: "invalid_grant" }));
+    await expect(
+      new GrokRefreshCoordinator({ fetch: unavailable.fetch }).refresh(
+        1,
+        credentials(),
+        async () => undefined,
+      ),
+    ).rejects.toMatchObject({ name: "GrokRefreshTransientError", status: 503 });
+    const offline = tokenFetch(() => {
+      throw new TypeError("fetch failed");
+    });
+    await expect(
+      new GrokRefreshCoordinator({ fetch: offline.fetch }).refresh(
+        1,
+        credentials(),
+        async () => undefined,
+      ),
+    ).rejects.toBeInstanceOf(GrokRefreshTransientError);
+  });
+
+  it("coalesces concurrent refreshes of one token into one HTTP call", async () => {
+    let release: (() => void) | undefined;
+    const gate = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    const { fetch, bodies } = tokenFetch(async () => {
+      await gate;
+      return json(200, { access_token: accessToken("new"), expires_in: 60 });
+    });
+    let persists = 0;
+    const persist = async (): Promise<void> => {
+      persists += 1;
+    };
+    const coordinator = new GrokRefreshCoordinator({ fetch, now: () => NOW });
+    const first = coordinator.refresh(9, credentials(), persist);
+    const second = coordinator.refresh(9, credentials(), persist);
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    release?.();
+    const [a, b] = await Promise.all([first, second]);
+    expect(a).toBe(b);
+    expect(bodies).toHaveLength(1);
+    expect(persists).toBe(1);
+
+    // After settling, a new call makes a new request.
+    await coordinator.refresh(9, a, persist);
+    expect(bodies).toHaveLength(2);
+  });
+
+  it("rejects when persistence fails", async () => {
+    const { fetch } = tokenFetch(() => json(200, { access_token: accessToken("new"), expires_in: 60 }));
+    await expect(
+      new GrokRefreshCoordinator({ fetch }).refresh(1, credentials(), async () => {
+        throw new Error("db down");
+      }),
+    ).rejects.toThrow("db down");
+  });
+
+  it("rejects a non-at+jwt access token in the refresh response", async () => {
+    const { fetch } = tokenFetch(() => json(200, { access_token: "xai-key", expires_in: 60 }));
+    await expect(
+      new GrokRefreshCoordinator({ fetch }).refresh(1, credentials(), async () => undefined),
+    ).rejects.toBeInstanceOf(GrokRefreshTransientError);
+  });
+});
+
+describe("GrokRefresher port", () => {
+  it("ensureFresh skips fresh tokens and refreshes stale ones", async () => {
+    const { fetch, bodies } = tokenFetch(() =>
+      json(200, { access_token: accessToken("new"), expires_in: 21_600 }),
+    );
+    const stored: number[] = [];
+    const coordinator = new GrokRefreshCoordinator({
+      fetch,
+      now: () => NOW,
+      persist: async (tokenId) => {
+        stored.push(tokenId);
+      },
+    });
+    const fresh = credentials({ expiresAt: new Date(NOW + 3_600_000).toISOString() });
+    expect(await coordinator.ensureFresh({ tokenId: 3, credentials: fresh })).toBe(fresh);
+    expect(bodies).toHaveLength(0);
+
+    const stale = credentials({ expiresAt: new Date(NOW + 60_000).toISOString() });
+    const next = await coordinator.ensureFresh({ tokenId: 3, credentials: stale });
+    expect(next.accessToken).toBe(accessToken("new"));
+    expect(stored).toEqual([3]);
+  });
+
+  it("refreshAfterUnauthorized reuses an already-replaced token and maps invalid_grant", async () => {
+    let reply = (): Response => json(200, { access_token: accessToken("new"), expires_in: 21_600 });
+    const { fetch, bodies } = tokenFetch(() => reply());
+    const coordinator = new GrokRefreshCoordinator({
+      fetch,
+      now: () => NOW,
+      persist: async () => undefined,
+    });
+    const first = await coordinator.refreshAfterUnauthorized({ tokenId: 4, credentials: credentials() });
+    expect(first.status).toBe("refreshed");
+    const second = await coordinator.refreshAfterUnauthorized({
+      tokenId: 4,
+      credentials: credentials(),
+    });
+    expect(second).toEqual(first);
+    expect(bodies).toHaveLength(1);
+
+    reply = () => json(400, { error: "invalid_grant" });
+    const fresh = first.status === "refreshed" ? first.credentials : credentials();
+    expect(
+      await coordinator.refreshAfterUnauthorized({ tokenId: 4, credentials: fresh }),
+    ).toEqual({ status: "reauth_required", reason: "invalid_grant" });
+  });
+});