feat(usage): fetch SuperGrok weekly pool via gRPC-web

Decode GetGrokCreditsConfig frames when REST billing returns empty caps, so SuperGrok weekly quota shows in the usage dashboard. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-09-22 13:38:31 +00:00 · 2026-07-29 18:09:43 +07:00
parent 6eaa9f8369
commit f17a68aaee
4 changed files with 619 additions and 5 deletions
@@ -0,0 +1,229 @@
+import { describe, it, expect } from "vitest";
+import {
+  decodeGrokCreditsFrame,
+  probeFrameHeader,
+} from "../../open-sse/services/usage/grokCliQuotaFrame.js";
+
+/**
+ * Minimal protobuf encoder for fixtures — real GetGrokCreditsConfig wire shape
+ * (nested field 1 / fixed32 ratio / Timestamp reset + optional trailer 0x80).
+ */
+
+function encodeVarint(value) {
+  const bytes = [];
+  let v = BigInt(value);
+  do {
+    let byte = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v !== 0n) byte |= 0x80;
+    bytes.push(byte);
+  } while (v !== 0n);
+  return Buffer.from(bytes);
+}
+
+function encodeTag(fieldNumber, wireType) {
+  return encodeVarint((fieldNumber << 3) | wireType);
+}
+
+function encodeFixed32Field(fieldNumber, value) {
+  const body = Buffer.alloc(4);
+  body.writeFloatLE(value, 0);
+  return Buffer.concat([encodeTag(fieldNumber, 5), body]);
+}
+
+function encodeLengthDelimited(fieldNumber, body) {
+  return Buffer.concat([encodeTag(fieldNumber, 2), encodeVarint(body.length), body]);
+}
+
+function encodeVarintField(fieldNumber, value) {
+  return Buffer.concat([encodeTag(fieldNumber, 0), encodeVarint(value)]);
+}
+
+function encodeTimestampField(fieldNumber, seconds, nanos) {
+  const parts = [];
+  if (seconds !== 0) parts.push(encodeVarintField(1, seconds));
+  if (nanos !== 0) parts.push(encodeVarintField(2, nanos));
+  return encodeLengthDelimited(fieldNumber, Buffer.concat(parts));
+}
+
+function encodeCreditsInfo(shape) {
+  const parts = [];
+  if (shape.usageRatio !== undefined) parts.push(encodeFixed32Field(1, shape.usageRatio));
+  if (shape.asOfSeconds !== undefined) {
+    parts.push(encodeTimestampField(4, shape.asOfSeconds, shape.asOfNanos ?? 0));
+  }
+  if (shape.resetSeconds !== undefined) {
+    parts.push(encodeTimestampField(5, shape.resetSeconds, shape.resetNanos ?? 0));
+  }
+  return Buffer.concat(parts);
+}
+
+function encodeTopLevelMessage(creditsInfo) {
+  return encodeLengthDelimited(1, creditsInfo);
+}
+
+function frameData(payload) {
+  const header = Buffer.alloc(5);
+  header[0] = 0x00;
+  header.writeUInt32BE(payload.length, 1);
+  return Buffer.concat([header, payload]);
+}
+
+function frameTrailer(statusText = "grpc-status:0\r\n") {
+  const body = Buffer.from(statusText, "utf8");
+  const header = Buffer.alloc(5);
+  header[0] = 0x80;
+  header.writeUInt32BE(body.length, 1);
+  return Buffer.concat([header, body]);
+}
+
+const REAL_USAGE_RATIO = 1.0;
+const REAL_ASOF_SECONDS = 1784221140;
+const REAL_ASOF_NANOS = 867850000;
+const REAL_RESET_SECONDS = 1784825940;
+const REAL_RESET_NANOS = 867850000;
+const PERCENT_TOLERANCE = 1e-4;
+
+function isoFromEpoch(seconds, nanos) {
+  return new Date(seconds * 1000 + Math.round(nanos / 1_000_000)).toISOString();
+}
+
+describe("decodeGrokCreditsFrame", () => {
+  it("decodes real GetGrokCreditsConfig shape (nested, fixed32, Timestamp, trailer)", () => {
+    const creditsInfo = encodeCreditsInfo({
+      usageRatio: REAL_USAGE_RATIO,
+      asOfSeconds: REAL_ASOF_SECONDS,
+      asOfNanos: REAL_ASOF_NANOS,
+      resetSeconds: REAL_RESET_SECONDS,
+      resetNanos: REAL_RESET_NANOS,
+    });
+    const buffer = Buffer.concat([frameData(encodeTopLevelMessage(creditsInfo)), frameTrailer()]);
+
+    const result = decodeGrokCreditsFrame(buffer);
+    expect(result).toBeTruthy();
+    expect(result.percentUsed).toBe(100);
+    expect(result.resetAt).toBe(isoFromEpoch(REAL_RESET_SECONDS, REAL_RESET_NANOS));
+  });
+
+  it("ignores trailing gRPC-web trailer frame (flag 0x80)", () => {
+    const creditsInfo = encodeCreditsInfo({
+      usageRatio: 0.5,
+      resetSeconds: REAL_RESET_SECONDS,
+      resetNanos: 0,
+    });
+    const topMessage = encodeTopLevelMessage(creditsInfo);
+    const withoutTrailer = frameData(topMessage);
+    const withTrailer = Buffer.concat([frameData(topMessage), frameTrailer()]);
+
+    const a = decodeGrokCreditsFrame(withoutTrailer);
+    const b = decodeGrokCreditsFrame(withTrailer);
+    expect(a).toBeTruthy();
+    expect(b).toBeTruthy();
+    expect(b.percentUsed).toBe(a.percentUsed);
+    expect(b.resetAt).toBe(a.resetAt);
+    expect(b.percentUsed).toBe(50);
+  });
+
+  it("decodes raw unframed protobuf payload", () => {
+    const creditsInfo = encodeCreditsInfo({
+      usageRatio: 0.75,
+      resetSeconds: REAL_RESET_SECONDS,
+      resetNanos: REAL_RESET_NANOS,
+    });
+    const payload = encodeTopLevelMessage(creditsInfo);
+    expect(probeFrameHeader(payload)).toBeNull();
+
+    const result = decodeGrokCreditsFrame(payload);
+    expect(result).toBeTruthy();
+    expect(Math.abs(result.percentUsed - 75)).toBeLessThan(PERCENT_TOLERANCE);
+    expect(result.resetAt).toBe(isoFromEpoch(REAL_RESET_SECONDS, REAL_RESET_NANOS));
+  });
+
+  it("treats omitted usage-ratio as 0% (proto3 default)", () => {
+    const creditsInfo = encodeCreditsInfo({
+      resetSeconds: REAL_RESET_SECONDS,
+      resetNanos: REAL_RESET_NANOS,
+    });
+    const result = decodeGrokCreditsFrame(frameData(encodeTopLevelMessage(creditsInfo)));
+    expect(result).toBeTruthy();
+    expect(result.percentUsed).toBe(0);
+    expect(result.resetAt).toBe(isoFromEpoch(REAL_RESET_SECONDS, REAL_RESET_NANOS));
+  });
+
+  it("clamps usage ratio above 1.0 to percentUsed 100", () => {
+    const creditsInfo = encodeCreditsInfo({ usageRatio: 1.5 });
+    const result = decodeGrokCreditsFrame(frameData(encodeTopLevelMessage(creditsInfo)));
+    expect(result).toBeTruthy();
+    expect(result.percentUsed).toBe(100);
+  });
+
+  it("returns null for negative usage ratio", () => {
+    const creditsInfo = encodeCreditsInfo({ usageRatio: -0.1 });
+    expect(decodeGrokCreditsFrame(frameData(encodeTopLevelMessage(creditsInfo)))).toBeNull();
+  });
+
+  it("returns null when top-level field 1 is not length-delimited", () => {
+    expect(decodeGrokCreditsFrame(frameData(encodeVarintField(1, 42)))).toBeNull();
+  });
+
+  it("returns null when nested usage-ratio has unexpected wire type", () => {
+    const creditsInfo = encodeLengthDelimited(1, Buffer.from("not-a-float", "utf8"));
+    expect(decodeGrokCreditsFrame(frameData(encodeTopLevelMessage(creditsInfo)))).toBeNull();
+  });
+
+  it("returns null when top-level has no field 1", () => {
+    expect(decodeGrokCreditsFrame(frameData(encodeVarintField(9, 1)))).toBeNull();
+  });
+
+  it("returns null for truncated buffer", () => {
+    const creditsInfo = encodeCreditsInfo({
+      usageRatio: 0.5,
+      resetSeconds: REAL_RESET_SECONDS,
+      resetNanos: REAL_RESET_NANOS,
+    });
+    const buffer = frameData(encodeTopLevelMessage(creditsInfo));
+    expect(decodeGrokCreditsFrame(buffer.subarray(0, buffer.length - 3))).toBeNull();
+  });
+
+  it("returns null for trailer-only body", () => {
+    expect(decodeGrokCreditsFrame(frameTrailer())).toBeNull();
+  });
+
+  it("returns null for empty buffer", () => {
+    expect(decodeGrokCreditsFrame(Buffer.alloc(0))).toBeNull();
+  });
+});
+
+describe("probeFrameHeader", () => {
+  it("rejects declared length that exceeds body", () => {
+    const header = Buffer.alloc(5);
+    header[0] = 0x00;
+    header.writeUInt32BE(9999, 1);
+    expect(probeFrameHeader(Buffer.concat([header, Buffer.from([0x01, 0x02])]))).toBeNull();
+  });
+
+  it("rejects invalid compression flag", () => {
+    const header = Buffer.alloc(5);
+    header[0] = 0x07;
+    expect(probeFrameHeader(header)).toBeNull();
+  });
+
+  it("accepts trailer frame header (flag 0x80)", () => {
+    const result = probeFrameHeader(frameTrailer());
+    expect(result).toBeTruthy();
+    expect(result.flag).toBe(0x80);
+  });
+
+  it("reads frame header at non-zero offset", () => {
+    const creditsInfo = encodeCreditsInfo({ usageRatio: 0.5 });
+    const buffer = Buffer.concat([
+      frameData(encodeTopLevelMessage(creditsInfo)),
+      frameTrailer(),
+    ]);
+    const first = probeFrameHeader(buffer);
+    expect(first).toBeTruthy();
+    const second = probeFrameHeader(buffer, first.payloadStart + first.payloadLength);
+    expect(second).toBeTruthy();
+    expect(second.flag).toBe(0x80);
+  });
+});
@@ -169,6 +169,67 @@ describe("parseGrokCliBilling", () => {
  });
 });

+function encodeVarint(value) {
+  const bytes = [];
+  let v = BigInt(value);
+  do {
+    let byte = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v !== 0n) byte |= 0x80;
+    bytes.push(byte);
+  } while (v !== 0n);
+  return Buffer.from(bytes);
+}
+
+function encodeTag(fieldNumber, wireType) {
+  return encodeVarint((fieldNumber << 3) | wireType);
+}
+
+function encodeFixed32Field(fieldNumber, value) {
+  const body = Buffer.alloc(4);
+  body.writeFloatLE(value, 0);
+  return Buffer.concat([encodeTag(fieldNumber, 5), body]);
+}
+
+function encodeLengthDelimited(fieldNumber, body) {
+  return Buffer.concat([encodeTag(fieldNumber, 2), encodeVarint(body.length), body]);
+}
+
+function encodeVarintField(fieldNumber, value) {
+  return Buffer.concat([encodeTag(fieldNumber, 0), encodeVarint(value)]);
+}
+
+function encodeTimestampField(fieldNumber, seconds, nanos) {
+  const parts = [];
+  if (seconds !== 0) parts.push(encodeVarintField(1, seconds));
+  if (nanos !== 0) parts.push(encodeVarintField(2, nanos));
+  return encodeLengthDelimited(fieldNumber, Buffer.concat(parts));
+}
+
+/** Framed GetGrokCreditsConfig response for a usage ratio 0..1. */
+function buildCreditsResponseBuffer(usageRatio, resetSeconds = 1784825940, resetNanos = 867850000) {
+  const creditsInfo = Buffer.concat([
+    encodeFixed32Field(1, usageRatio),
+    encodeTimestampField(5, resetSeconds, resetNanos),
+  ]);
+  const topMessage = encodeLengthDelimited(1, creditsInfo);
+  const header = Buffer.alloc(5);
+  header[0] = 0x00;
+  header.writeUInt32BE(topMessage.length, 1);
+  return Buffer.concat([header, topMessage]);
+}
+
+function binaryResponse(buffer, status = 200) {
+  return new Response(buffer, {
+    status,
+    headers: { "content-type": "application/grpc-web+proto" },
+  });
+}
+
+const EMPTY_GRPC_WEB_FRAME = Buffer.from([0, 0, 0, 0, 0]);
+const GRPC_CREDITS_URL =
+  "https://grok.com/grok_api_v2.GrokBuildBilling/GetGrokCreditsConfig";
+
 describe("getUsageForProvider(grok-cli)", () => {
  beforeEach(() => {
    vi.clearAllMocks();
@@ -211,6 +272,8 @@ describe("getUsageForProvider(grok-cli)", () => {
    expect(billingCall[1].headers["x-userid"]).toBe(
      "d84768dd-224d-4052-ba49-0d336fa9160c",
    );
+    // REST already has numeric quotas — do not hit gRPC fallback
+    expect(proxyAwareFetch.mock.calls).toHaveLength(2);
  });

  it("surfaces auth-expired message on 401", async () => {
@@ -224,6 +287,8 @@ describe("getUsageForProvider(grok-cli)", () => {
    });

    expect(usage.message).toMatch(/expired|re-authorize/i);
+    // Auth failure must not attempt gRPC fallback
+    expect(proxyAwareFetch.mock.calls).toHaveLength(2);
  });

  it("returns depleted on-demand bar without blocking message when cap is zero", async () => {
@@ -241,15 +306,62 @@ describe("getUsageForProvider(grok-cli)", () => {
    expect(usage.message).toBeUndefined();
    expect(usage.quotas["On-demand"].remainingPercentage).toBe(0);
    expect(usage.quotas["On-demand"].total).toBe(1);
+    // Exhausted free already has a quota bar — no gRPC fallback
+    expect(proxyAwareFetch.mock.calls).toHaveLength(2);
  });

-  it("reports active paid access when provider exposes no numeric quota", async () => {
+  it("falls back to GetGrokCreditsConfig gRPC when paid sub has no REST numeric quota", async () => {
+    const resetSeconds = 1784825940;
+    const resetNanos = 867850000;
+    const resetAt = new Date(
+      resetSeconds * 1000 + Math.round(resetNanos / 1_000_000),
+    ).toISOString();
+
    proxyAwareFetch
      .mockResolvedValueOnce(jsonResponse(EXHAUSTED_BILLING))
-      .mockResolvedValueOnce(jsonResponse({
-        ...USER_PROFILE,
-        subscriptionTier: "XPremiumPlus",
-      }));
+      .mockResolvedValueOnce(
+        jsonResponse({
+          ...USER_PROFILE,
+          subscriptionTier: "XPremiumPlus",
+        }),
+      )
+      .mockResolvedValueOnce(binaryResponse(buildCreditsResponseBuffer(0.35, resetSeconds, resetNanos)));
+
+    const usage = await getUsageForProvider({
+      provider: "grok-cli",
+      accessToken: "test-token",
+    });
+
+    expect(usage.message).toBeUndefined();
+    expect(usage.plan).toBe("XPremiumPlus");
+    expect(usage.quotas["Weekly SuperGrok"]).toMatchObject({
+      used: 35,
+      total: 100,
+      remainingPercentage: 65,
+      resetAt,
+      unlimited: false,
+    });
+
+    const grpcCall = proxyAwareFetch.mock.calls[2];
+    expect(grpcCall[0]).toBe(GRPC_CREDITS_URL);
+    expect(grpcCall[1].method).toBe("POST");
+    expect(grpcCall[1].headers.Authorization).toBe("Bearer test-token");
+    expect(grpcCall[1].headers["Content-Type"]).toBe("application/grpc-web+proto");
+    expect(grpcCall[1].headers["X-Grpc-Web"]).toBe("1");
+    // Empty gRPC-web request frame is required (flag 0 + length 0)
+    expect(Buffer.from(grpcCall[1].body)).toEqual(EMPTY_GRPC_WEB_FRAME);
+  });
+
+  it("keeps subscription message when REST empty and gRPC fails open", async () => {
+    proxyAwareFetch
+      .mockResolvedValueOnce(jsonResponse(EXHAUSTED_BILLING))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          ...USER_PROFILE,
+          subscriptionTier: "XPremiumPlus",
+        }),
+      )
+      .mockResolvedValueOnce(binaryResponse(Buffer.alloc(0), 500));

    const usage = await getUsageForProvider({
      provider: "grok-cli",
@@ -260,6 +372,26 @@ describe("getUsageForProvider(grok-cli)", () => {
    expect(usage.message).toMatch(/active.*numeric included quota/i);
    expect(usage.quotas).toEqual({});
  });
+
+  it("does not throw when gRPC network fails after empty REST quotas", async () => {
+    proxyAwareFetch
+      .mockResolvedValueOnce(jsonResponse(EXHAUSTED_BILLING))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          ...USER_PROFILE,
+          subscriptionTier: "XPremiumPlus",
+        }),
+      )
+      .mockRejectedValueOnce(new Error("network down"));
+
+    const usage = await getUsageForProvider({
+      provider: "grok-cli",
+      accessToken: "test-token",
+    });
+
+    expect(usage.message).toMatch(/active.*numeric included quota/i);
+    expect(usage.quotas).toEqual({});
+  });
 });

 describe("parseQuotaData(grok-cli)", () => {