PaperClipAI/server/src/services/ai-connection-usage.test.ts

import { describe, expect, it, vi } from "vitest";
import { probeAiConnectionUsage } from "./ai-connection-usage.js";

const auth = JSON.stringify({ tokens: { access_token: "selected-access-secret", account_id: "selected-account" } });
function fixture(body: unknown, status = 200) {
  return vi.fn<typeof fetch>().mockResolvedValue(new Response(JSON.stringify(body), { status }));
}

describe("connection usage probes", () => {
  it("reads every Codex window, preserves percentages and separates model restrictions", async () => {
    const request = fixture({ plan_type: "pro", rate_limit: {
      allowed: true, limit_reached: false,
      primary_window: { used_percent: 0.4, limit_window_seconds: 14400, reset_at: 1800000000 },
      secondary_window: { used_percent: 99.99, limit_window_seconds: 604800 },
    }, additional_rate_limits: [{ limit_name: "Spark", metered_feature: "spark", rate_limit: {
      allowed: false, limit_reached: true, primary_window: { used_percent: 101.2, limit_window_seconds: 7200 },
    } }], credits: { has_credits: true, unlimited: false, balance: "25.5" } });
    const result = await probeAiConnectionUsage({ provider: "openai", method: "subscription" }, auth, { request });
    expect(result.status).toBe("ok");
    expect(result.limits).toHaveLength(3);
    expect(result.limits[0]).toMatchObject({ scope: null, usedPercent: 0.4, remainingPercent: 99.6, windowDurationSeconds: 14400, resetsAt: new Date(1800000000000).toISOString() });
    expect(result.limits[1]).toMatchObject({ usedPercent: 99.99, limitReached: false, resetsAt: null });
    expect(result.limits[2]).toMatchObject({ scope: "spark", usedPercent: 101.2, remainingPercent: 0, limitReached: true, allowed: false });
    expect(result.overage).toMatchObject({ enabled: null, available: true, balance: 25.5, unit: "credits" });
    expect(request).toHaveBeenCalledWith("https://chatgpt.com/backend-api/wham/usage", expect.objectContaining({
      redirect: "error", signal: expect.any(AbortSignal),
      headers: { Authorization: "Bearer selected-access-secret", "ChatGPT-Account-Id": "selected-account" },
    }));
    expect(JSON.stringify(result)).not.toContain("selected-access-secret");
  });

  it("keeps group denial without pretending every Codex window is exhausted", async () => {
    const result = await probeAiConnectionUsage({ provider: "openai", method: "subscription" }, auth, { request: fixture({
      rate_limit: { allowed: false, limit_reached: true, primary_window: { used_percent: 100 }, secondary_window: { used_percent: 25 } },
      code_review_rate_limit: { allowed: false, limit_reached: true },
      spend_control: { reached: true }, credits: { has_credits: false, unlimited: false, balance: "0" },
    }) });
    expect(result.limits).toHaveLength(4);
    expect(result.limits[1]).toMatchObject({ limitReached: false, allowed: false });
    expect(result.limits[2]).toMatchObject({ scope: "code_review", limitReached: true });
    expect(result.overage?.available).toBe(false);
  });

  it("reports all Claude scopes and distinguishes extra-usage settings from availability", async () => {
    const request = fixture({ five_hour: { utilization: 100, resets_at: "2026-10-03T01:00:00Z" },
      seven_day: { utilization: 0.5 }, seven_day_opus: { utilization: null },
      seven_day_oauth_apps: { utilization: 33 }, future_window: { utilization: 10, resets_at: null },
      extra_usage: { is_enabled: true, monthly_limit: 5000, used_credits: 1000, utilization: 20 },
    });
    const result = await probeAiConnectionUsage({ provider: "anthropic", method: "subscription" }, "claude-selected-secret", { request });
    expect(result.status).toBe("ok");
    expect(result.limits).toHaveLength(6);
    expect(result.limits[0]).toMatchObject({ usedPercent: 100, limitReached: true, windowDurationSeconds: 18000 });
    expect(result.limits[1]).toMatchObject({ usedPercent: 0.5, remainingPercent: 99.5, windowDurationSeconds: 604800 });
    expect(result.limits[2]).toMatchObject({ usedPercent: null, limitReached: null });
    expect(result.limits[3].scope).toBe("seven_day_oauth_apps");
    expect(result.overage).toMatchObject({ enabled: true, available: null, remaining: 4000, unit: "cents" });
    expect(request).toHaveBeenCalledWith("https://api.anthropic.com/api/oauth/usage", expect.objectContaining({
      headers: { Authorization: "Bearer claude-selected-secret", "anthropic-beta": "oauth-2025-04-20" },
    }));
  });

  it.each([
    { is_enabled: false, available: false },
    { is_enabled: true, monthly_limit: 100, used_credits: 100, available: false },
  ])("reports unavailable Claude overage without inventing remaining allowance", async ({ available, ...extra_usage }) => {
    const result = await probeAiConnectionUsage({ provider: "anthropic", method: "subscription" }, "token", {
      request: fixture({ five_hour: { utilization: 100 }, extra_usage }),
    });
    expect(result.overage?.available).toBe(available);
  });

  it("reads Claude's structured limits, merges legacy aliases, and keeps every scoped window", async () => {
    const result = await probeAiConnectionUsage({ provider: "anthropic", method: "subscription" }, "token", {
      request: fixture({ five_hour: { utilization: 15 }, seven_day: { utilization: 25 }, seven_day_sonnet: { utilization: 50 },
        limits: [
          { kind: "session", percent: 16, scope: null, is_active: false },
          { kind: "weekly_all", percent: 26, scope: null, is_active: true },
          { kind: "weekly_scoped", percent: 100, scope: { model: { id: "sonnet", display_name: "Sonnet" }, surface: null }, is_active: false },
          { kind: "weekly_scoped", percent: 40, scope: { model: { id: "sonnet" }, surface: "code" } },
          { kind: "weekly_scoped", percent: 0, scope: { model: { id: null, display_name: null }, surface: null }, resets_at: "2026-10-05T04:00:00Z" },
          { kind: "session", group: "other", percent: 12, scope: null },
          { kind: "future", percent: 0.5, scope: { surface: "chat" } },
        ],
      }),
    });
    expect(result.status).toBe("ok");
    expect(result.limits).toHaveLength(7);
    expect(result.limits[0]).toMatchObject({ id: "five_hour", usedPercent: 16, scope: null, allowed: null });
    expect(result.limits[1]).toMatchObject({ id: "seven_day", usedPercent: 26, allowed: null });
    expect(result.limits[2]).toMatchObject({ id: "seven_day_sonnet", usedPercent: 100, scope: "model:sonnet", limitReached: true });
    expect(result.limits[3]).toMatchObject({ usedPercent: 40, scope: "model:sonnet · surface:code", windowDurationSeconds: 604800 });
    expect(result.limits[4]).toMatchObject({ scope: "weekly_scoped.4", usedPercent: 0, resetsAt: "2026-10-05T04:00:00.000Z" });
    expect(new Set(result.limits.map((entry) => entry.id)).size).toBe(7);
    expect(result.limits[6]).toMatchObject({ scope: "surface:chat", usedPercent: 0.5, windowDurationSeconds: null });
  });

  it("reads structured Claude spend when legacy extra_usage is absent, with its currency and exponent", async () => {
    const result = await probeAiConnectionUsage({ provider: "anthropic", method: "subscription" }, "token", {
      request: fixture({ limits: [{ kind: "session", percent: 30 }], spend: {
        enabled: true, percent: 25,
        used: { amount_minor: 1250, currency: "USD", exponent: 2 },
        limit: { amount_minor: 5000, currency: "USD", exponent: 2 },
        balance: { amount_minor: 2000, currency: "USD", exponent: 2 },
      } }),
    });
    expect(result.overage).toMatchObject({ enabled: true, available: null, used: 12.5, limit: 50, remaining: 37.5, balance: 20, unit: "USD" });
    expect(result.limits[1]).toMatchObject({ usedPercent: 25, used: 12.5, limit: 50, unit: "USD" });
  });

  it("keeps exhausted Claude groups separate from account-wide limits and preserves group identity across ordering", async () => {
    const structured = [
      { kind: "session", group: "chat", percent: 100, scope: null },
      { kind: "session", group: "code", percent: 25, scope: null },
      { kind: "weekly_all", group: "chat", percent: 105, scope: null },
      { kind: "weekly_all", group: "code", percent: 50, scope: null },
      { kind: "weekly_scoped", group: "code", percent: 60, scope: { model: { id: "sonnet" } } },
    ];
    const probe = (limits: unknown[]) => probeAiConnectionUsage({ provider: "anthropic", method: "subscription" }, "token", {
      request: fixture({ five_hour: { utilization: 10 }, seven_day: { utilization: 20 }, seven_day_sonnet: { utilization: 30 }, limits }),
    });
    const result = await probe(structured);
    expect(result.status).toBe("ok");
    expect(result.limits).toHaveLength(8);
    expect(result.limits[0]).toMatchObject({ id: "five_hour", scope: null, usedPercent: 10, limitReached: false });
    expect(result.limits[1]).toMatchObject({ id: "seven_day", scope: null, usedPercent: 20, limitReached: false });
    expect(result.limits[2]).toMatchObject({ id: "seven_day_sonnet", scope: "seven_day_sonnet", usedPercent: 30 });
    expect(result.limits[3]).toMatchObject({ scope: "group:chat", usedPercent: 100, limitReached: true });
    expect(result.limits[4]).toMatchObject({ scope: "group:code", usedPercent: 25, limitReached: false });
    expect(result.limits[7]).toMatchObject({ scope: "group:code · model:sonnet", usedPercent: 60 });
    expect(result.limits[3].label).toContain("chat");
    expect(new Set(result.limits.map((entry) => entry.id)).size).toBe(8);
    const reversed = await probe([...structured].reverse());
    expect(Object.fromEntries(reversed.limits.map((entry) => [entry.id, entry.scope])))
      .toEqual(Object.fromEntries(result.limits.map((entry) => [entry.id, entry.scope])));
  });

  it("reports a zero extra-usage cap as exhausted without dividing by zero", async () => {
    const result = await probeAiConnectionUsage({ provider: "anthropic", method: "subscription" }, "token", {
      request: fixture({ five_hour: { utilization: 10 }, extra_usage: { is_enabled: true, monthly_limit: 0, used_credits: 0 } }),
    });
    expect(result.limits[1]).toMatchObject({ usedPercent: null, remaining: 0, limitReached: true });
    expect(result.overage).toMatchObject({ enabled: true, available: false });
  });

  const grokAuth = JSON.stringify({ "https://auth.x.ai::00000000-0000-4000-8000-000000000001": { key: "grok-selected-secret", refresh_token: "never-exchange" } });
  it("uses Grok subscription billing and keeps plan credits separate from on-demand credits", async () => {
    const request = fixture({ onDemandEnabled: true, config: {
      creditUsagePercent: 35.5, currentPeriod: { start: "2026-10-01T00:00:00Z", end: "2026-10-08T00:00:00Z" },
      onDemandCap: { val: 200 }, onDemandUsed: { val: 150 }, prepaidBalance: { val: 100 },
    } });
    const result = await probeAiConnectionUsage({ provider: "xai", method: "subscription" }, grokAuth, { request });
    expect(result.status).toBe("ok");
    expect(result.limits[0]).toMatchObject({ usedPercent: 35.5, limit: null, windowDurationSeconds: 604800, unit: "cents" });
    expect(result.limits[1]).toMatchObject({ scope: "overage", usedPercent: 75 });
    expect(result.overage).toMatchObject({ enabled: true, available: null, remaining: 50, balance: 100 });
    expect(request).toHaveBeenCalledWith("https://cli-chat-proxy.grok.com/v1/billing?format=credits", expect.objectContaining({
      headers: expect.objectContaining({ Authorization: "Bearer grok-selected-secret", "x-xai-token-auth": "xai-grok-cli" }),
    }));
  });
  it("preserves the live Grok shape's omitted included usage instead of assuming zero", async () => {
    const result = await probeAiConnectionUsage({ provider: "xai", method: "subscription" }, grokAuth, {
      request: fixture({ config: {
        currentPeriod: { type: "USAGE_PERIOD_TYPE_WEEKLY", start: "2026-10-01T00:00:00Z", end: "2026-10-08T00:00:00Z" },
        isUnifiedBillingUser: true, onDemandCap: { val: 0 }, onDemandUsed: { val: 0 }, prepaidBalance: { val: 0 },
      } }),
    });
    expect(result.status).toBe("ok");
    expect(result.limits[0]).toMatchObject({ usedPercent: null, used: null, limit: null, limitReached: null, allowed: null, windowDurationSeconds: 604800 });
    expect(result.overage).toMatchObject({ enabled: null, available: false, balance: 0, unit: "cents" });
  });

  it("uses Grok's legacy used field, proto3 zero messages, and remote settings without conflating prepaid balance", async () => {
    const result = await probeAiConnectionUsage({ provider: "xai", method: "subscription" }, grokAuth, {
      request: fixture({ on_demand_enabled: true, subscription_tier: "SuperGrok", config: {
        monthlyLimit: { val: 2000 }, used: { val: 500 }, onDemandCap: {}, onDemandUsed: {}, prepaidBalance: { val: 100 },
        billingPeriodStart: "2026-10-01T00:00:00Z", billingPeriodEnd: "2026-11-01T00:00:00Z",
      } }),
    });
    expect(result.planType).toBe("SuperGrok");
    expect(result.limits[0]).toMatchObject({ used: 500, limit: 2000, usedPercent: 25, remaining: 1500, unit: "cents" });
    expect(result.overage).toMatchObject({ enabled: true, used: 0, limit: 0, remaining: 0, balance: 100, available: null });
  });
  it("does not infer Grok cadence or zero usage from just a reset timestamp", async () => {
    const result = await probeAiConnectionUsage({ provider: "xai", method: "subscription" }, grokAuth, {
      request: fixture({ config: { currentPeriod: { end: "2026-10-08T00:00:00Z" } } }),
    });
    expect(result).toMatchObject({ status: "error", errorCode: "invalid_response", limits: [] });
  });

  it("reads OpenRouter's key cap without dividing all-time usage by a resettable cap", async () => {
    const result = await probeAiConnectionUsage({ provider: "openrouter", method: "api_key" }, "key", {
      request: fixture({ data: { limit: 10, limit_remaining: 2, usage: 500, limit_reset: "weekly",
        free_model_daily_requests: { used: 50, limit: 50, remaining: 0 },
      } }),
    });
    expect(result.limits[0]).toMatchObject({ used: 8, usedPercent: 80, limitReached: false, resetInterval: "weekly", windowDurationSeconds: 604800 });
    expect(result.limits[1]).toMatchObject({ scope: "free_models", limitReached: true });
    expect(result.overage).toBe(null);
    const unknown = await probeAiConnectionUsage({ provider: "openrouter", method: "api_key" }, "key", {
      request: fixture({ data: { limit: 10, usage: 500, limit_reset: "weekly" } }),
    });
    expect(unknown.limits[0]).toMatchObject({ used: null, usedPercent: null, remaining: null, limitReached: null });
  });

  it("preserves an overdrawn OpenRouter key cap and does not turn an uncapped key into available credits", async () => {
    const overdrawn = await probeAiConnectionUsage({ provider: "openrouter", method: "api_key" }, "key", {
      request: fixture({ data: { limit: 10, limit_remaining: -2, usage: 200 } }),
    });
    expect(overdrawn.limits[0]).toMatchObject({ used: 12, usedPercent: 120, remaining: -2, limitReached: true });
    const unlimited = await probeAiConnectionUsage({ provider: "openrouter", method: "api_key" }, "key", {
      request: fixture({ data: { limit: null, limit_remaining: null, usage: 20 } }),
    });
    expect(unlimited).toMatchObject({ status: "ok", overage: null, limits: [{ used: 20, limit: null, usedPercent: null, limitReached: null }] });
  });

  it.each(["openai", "anthropic", "xai"] as const)("makes unsupported %s API probes explicit without a request", async provider => {
    const request = fixture({});
    expect(await probeAiConnectionUsage({ provider, method: "api_key" }, "key", { request })).toMatchObject({ status: "unsupported", limits: [], overage: null });
    expect(request).not.toHaveBeenCalled();
  });
  it.each([
    [401, "unavailable", "authentication_required"], [403, "unavailable", "permission_denied"],
    [429, "error", "rate_limited"], [503, "error", "provider_unavailable"],
  ])("does not misreport HTTP %s as exhausted subscription capacity", async (status, expected, code) => {
    const result = await probeAiConnectionUsage({ provider: "anthropic", method: "subscription" }, "token", {
      request: fixture({ error: "echoed-credential-secret" }, status as number),
    });
    expect(result).toMatchObject({ status: expected, errorCode: code, limits: [], overage: null });
    expect(JSON.stringify(result)).not.toContain("echoed-credential-secret");
  });
  it.each([{}, [], { five_hour: { utilization: -1 } }, { five_hour: { utilization: "100" } }])("fails closed on missing or malformed limits: %j", async body => {
    expect(await probeAiConnectionUsage({ provider: "anthropic", method: "subscription" }, "token", { request: fixture(body) })).toMatchObject({ status: "error", errorCode: "invalid_response" });
  });
  it("sanitizes network exceptions and refuses malformed credentials without a request", async () => {
    const request = vi.fn<typeof fetch>().mockRejectedValue(new Error("Authorization: secret"));
    expect(await probeAiConnectionUsage({ provider: "openai", method: "subscription" }, "not-json", { request })).toMatchObject({ status: "unavailable" });
    expect(request).not.toHaveBeenCalled();
    const result = await probeAiConnectionUsage({ provider: "openai", method: "subscription" }, auth, { request });
    expect(result.status).toBe("error");
    expect(JSON.stringify(result)).not.toContain("Authorization: secret");
  });
  it("bounds provider response bytes", async () => {
    const request = vi.fn<typeof fetch>().mockResolvedValue(new Response(" ".repeat(256 * 1024 + 1)));
    expect(await probeAiConnectionUsage({ provider: "anthropic", method: "subscription" }, "token", { request })).toMatchObject({ status: "error", errorCode: "invalid_response" });
  });
});