feat(usage): integrate ClinePass quota provider (#3431)

Add ClinePass across server and VS Code quota paths. Reject malformed windows, preserve valid sibling limits, align credential fallback, and report timeout failures accurately. Validated 30 server quota tests, 129 VS Code quota tests and VS Code type-check. Oxlint findings are confined to pre-existing VS Code code.
2026-09-09 17:51:39 +03:00
parent 70e04fc15f c9bcae5b04
commit 9ac78eaa9c
10 changed files with 494 additions and 1 deletions
@@ -15,6 +15,7 @@ const ORIGINAL_FS = { ...fs };
 const AUTH = JSON.stringify({
  openai: { access: 'test-token' },
  crof: { key: 'test-token' },
+  'cline-pass': { key: 'test-token' },
  neuralwatt: { key: 'test-token' },
  'opencode-go': { key: 'test-token' },
  openrouter: { key: 'test-token' },
@@ -27,7 +28,7 @@ const AUTH = JSON.stringify({
 ((fs as unknown) as { existsSync: () => boolean }).existsSync = () => true;
 ((fs as unknown) as { readFileSync: () => string }).readFileSync = () => AUTH;

-import { fetchHyperQuota, fetchOllamaCloudQuota, fetchQuotaForProvider } from './quotaProviders';
+import { fetchClinePassQuota, fetchHyperQuota, fetchOllamaCloudQuota, fetchQuotaForProvider } from './quotaProviders';
 import { validateCredential } from './quotaCredentials';

 type MockResponseInit = { ok?: boolean; status?: number };
@@ -336,6 +337,121 @@ describe('Crof quota provider (VS Code parity)', () => {
  });
 });

+describe('ClinePass quota provider (VS Code parity)', () => {
+  // Live-verified response shape of
+  // GET https://api.cline.bot/api/v1/users/me/plan/usage-limits
+  const documentedPayload = {
+    data: {
+      limits: [
+        { type: 'five_hour', percentUsed: 43, resetsAt: '2026-09-08T17:00:44.598174595Z' },
+        { type: 'weekly', percentUsed: 17, resetsAt: '2026-09-13T17:00:44.598174595Z' },
+        { type: 'monthly', percentUsed: 8, resetsAt: '2026-10-01T00:00:00Z' },
+      ],
+    },
+    success: true,
+  };
+
+  test('maps documented limit kinds to 5h/weekly/monthly windows', async () => {
+    stubFetchReturning(() => Promise.resolve(mockResponse(documentedPayload)));
+
+    const result = await fetchQuotaForProvider('cline-pass');
+
+    assert.equal(result.ok, true);
+    assert.equal(result.providerId, 'cline-pass');
+    assert.equal(result.usage?.windows['5h']?.usedPercent, 43);
+    assert.equal(result.usage?.windows['5h']?.windowSeconds, 18_000);
+    assert.equal(result.usage?.windows['5h']?.resetAt, Date.parse('2026-09-08T17:00:44.598174595Z'));
+    assert.equal(result.usage?.windows.weekly?.usedPercent, 17);
+    assert.equal(result.usage?.windows.weekly?.windowSeconds, 604_800);
+    assert.equal(result.usage?.windows.monthly?.usedPercent, 8);
+    assert.equal(result.usage?.windows.monthly?.windowSeconds, null);
+  });
+
+  test('ignores unknown limit types and rejects responses without quota data', async () => {
+    stubFetchReturning(() => Promise.resolve(mockResponse({ data: { limits: [{ type: 'quarterly', percentUsed: 5 }] } })));
+
+    const result = await fetchQuotaForProvider('cline-pass');
+
+    assert.equal(result.ok, false);
+    assert.equal(result.configured, true);
+    assert.equal(result.usage, null);
+    assert.equal(result.error, 'No quota data in response');
+  });
+
+  test('maps 401 to session-expired with ClinePass branding', async () => {
+    stubFetchFailing(async () => ({}), { ok: false, status: 401 });
+
+    const result = await fetchQuotaForProvider('cline-pass');
+
+    assert.equal(result.ok, false);
+    assert.equal(result.configured, true);
+    assert.equal(result.error, 'Session expired — please re-authenticate with ClinePass');
+  });
+
+  test('reports invalid-response on JSON parse failure', async () => {
+    stubFetchFailing(async () => { throw new SyntaxError('Unexpected token'); }, { ok: true, status: 200 });
+
+    const result = await fetchQuotaForProvider('cline-pass');
+
+    assert.equal(result.ok, false);
+    assert.equal(result.error, 'Invalid response from provider');
+  });
+
+  const readAuth = () => ({ 'cline-pass': { key: 'test-token' } });
+
+  for (const limit of [
+    { type: 'constructor', percentUsed: 5 }, { type: 'toString', percentUsed: 5 },
+    { type: '__proto__', percentUsed: 5 }, { type: 'weekly', percentUsed: '' },
+    { type: 'weekly', percentUsed: ' ' }, { type: 'weekly', percentUsed: true },
+    { type: 'weekly', percentUsed: null }, null,
+  ]) {
+    test(`skips malformed windows independently: ${JSON.stringify(limit)}`, async () => {
+      const invalid = await fetchClinePassQuota({ readAuth, fetchImpl: async () => Response.json({ data: { limits: [limit] } }) });
+      assert.equal(invalid.ok, false);
+      assert.equal(invalid.usage, null);
+      const mixed = await fetchClinePassQuota({ readAuth, fetchImpl: async () => Response.json({ data: { limits: [limit, { type: 'monthly', percentUsed: 8 }] } }) });
+      assert.equal(mixed.ok, true);
+      assert.ok(mixed.usage);
+      assert.deepEqual(Object.keys(mixed.usage.windows), ['monthly']);
+    });
+  }
+
+  for (const percentUsed of [0, '0', '51']) {
+    test(`accepts percentage ${JSON.stringify(percentUsed)}`, async () => {
+      const result = await fetchClinePassQuota({ readAuth, fetchImpl: async () => Response.json({ data: { limits: [{ type: 'weekly', percentUsed }] } }) });
+      assert.equal(result.ok, true);
+      assert.equal(result.usage?.windows.weekly?.usedPercent, Number(percentUsed));
+    });
+  }
+
+  for (const entry of [{ key: '' }, { key: ' ' }, { key: 42 }, {}]) {
+    test(`falls back to a usable token: ${JSON.stringify(entry)}`, async () => {
+      const result = await fetchClinePassQuota({
+        readAuth: () => ({ 'cline-pass': { ...entry, token: 'test-token' } }),
+        fetchImpl: async (_url, options) => {
+          assert.equal(new Headers(options.headers).get('Authorization'), 'Bearer test-token');
+          return Response.json(documentedPayload);
+        },
+      });
+      assert.equal(result.ok, true);
+    });
+  }
+
+  test('does not request usage without usable credentials', async () => {
+    const result = await fetchClinePassQuota({ readAuth: () => ({ 'cline-pass': { key: 42 } }), fetchImpl: async () => { throw new Error('Unexpected fetch'); } });
+    assert.equal(result.configured, false);
+    assert.equal(result.error, 'Not configured');
+  });
+
+  test('recognizes the timeout exception from AbortSignal.timeout', async () => {
+    const result = await fetchClinePassQuota({ readAuth, fetchImpl: async () => { throw new DOMException('Timed out', 'TimeoutError'); } });
+    assert.equal(result.ok, false);
+    assert.equal(result.configured, true);
+    assert.equal(result.usage, null);
+    assert.equal(result.error, 'Request timed out');
+  });
+});
+
 describe('Codex quota provider (VS Code parity)', () => {
  test('coalesces concurrent refreshes for the same provider', async () => {
    let resolveResponse: ((response: Response) => void) | undefined;
@@ -146,6 +146,11 @@ type CrofPayload = {
  credits?: number | string;
 };

+type ClineWindowKind = {
+  key: string;
+  windowSeconds: number | null;
+};
+
 type DeepseekPayload = {
  is_available?: boolean;
  balance_infos?: Array<{
@@ -844,6 +849,11 @@ export const listConfiguredQuotaProviders = () => {
    configured.add('crof');
  }

+  const clineAuth = normalizeAuthEntry(getAuthEntry(auth, ['cline-pass']));
+  if (clineAuth && (asNonEmptyString(clineAuth.key) || asNonEmptyString(clineAuth.token))) {
+    configured.add('cline-pass');
+  }
+
  const neuralwattAuth = normalizeAuthEntry(getAuthEntry(auth, ['neuralwatt']));
  if (neuralwattAuth && ((neuralwattAuth as Record<string, unknown>).key || (neuralwattAuth as Record<string, unknown>).token)) {
    configured.add('neuralwatt');
@@ -2745,6 +2755,118 @@ const fetchCrofQuota = async (): Promise<ProviderResult> => {
  }
 };

+const CLINE_PASS_USAGE_URL = 'https://api.cline.bot/api/v1/users/me/plan/usage-limits';
+
+// Cline reports a rolling five-hour window, a rolling weekly window, and a
+// calendar-month limit. Each window carries its duration so consumers can rank
+// limits by how soon they run out; the calendar month has no fixed duration.
+const CLINE_WINDOW_KINDS = new Map<string, ClineWindowKind>([
+  ['five_hour', { key: '5h', windowSeconds: 5 * 60 * 60 }],
+  ['weekly', { key: 'weekly', windowSeconds: 7 * 24 * 60 * 60 }],
+  ['monthly', { key: 'monthly', windowSeconds: null }],
+]);
+
+type ClineQuotaDependencies = {
+  readAuth?: () => AuthFile;
+  fetchImpl?: (url: string, options: RequestInit) => Promise<Response>;
+};
+
+export const fetchClinePassQuota = async ({ readAuth = readAuthFile, fetchImpl = fetch }: ClineQuotaDependencies = {}): Promise<ProviderResult> => {
+  const auth = readAuth();
+  const entry = normalizeAuthEntry(getAuthEntry(auth, ['cline-pass']));
+  const apiKey = asNonEmptyString(entry?.key) ?? asNonEmptyString(entry?.token);
+
+  if (!apiKey) {
+    return buildResult({
+      providerId: 'cline-pass',
+      providerName: 'ClinePass',
+      ok: false,
+      configured: false,
+      error: 'Not configured',
+    });
+  }
+
+  const timeoutSignal = AbortSignal.timeout(15_000);
+
+  try {
+    const response = await fetchImpl(CLINE_PASS_USAGE_URL, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Accept-Encoding': 'identity',
+      },
+      signal: timeoutSignal,
+    });
+
+    if (!response.ok) {
+      return buildResult({
+        providerId: 'cline-pass',
+        providerName: 'ClinePass',
+        ok: false,
+        configured: true,
+        error: response.status === 401
+          ? 'Session expired — please re-authenticate with ClinePass'
+          : `API error: ${response.status}`,
+      });
+    }
+
+    const payload = asObject(await response.json());
+    const data = asObject(payload?.data);
+    const limits = Array.isArray(data?.limits) ? data.limits : [];
+
+    const windows: Record<string, UsageWindow> = {};
+    for (const item of limits) {
+      const limit = asObject(item);
+      if (!limit) continue;
+      const limitType = asNonEmptyString(limit.type);
+      const kind = limitType === null ? undefined : CLINE_WINDOW_KINDS.get(limitType);
+      if (!kind) continue;
+      const usedPercent = toNumber(asNonEmptyString(limit.percentUsed)
+        ?? (Number.isFinite(limit.percentUsed) ? limit.percentUsed : null));
+      if (usedPercent === null) continue;
+      windows[kind.key] = toUsageWindow({
+        usedPercent,
+        windowSeconds: kind.windowSeconds,
+        resetAt: toTimestamp(limit.resetsAt),
+      });
+    }
+
+    if (Object.keys(windows).length === 0) {
+      return buildResult({
+        providerId: 'cline-pass',
+        providerName: 'ClinePass',
+        ok: false,
+        configured: true,
+        error: 'No quota data in response',
+      });
+    }
+
+    return buildResult({
+      providerId: 'cline-pass',
+      providerName: 'ClinePass',
+      ok: true,
+      configured: true,
+      usage: { windows },
+    });
+  } catch (error) {
+    const isTimeout = error instanceof DOMException && (
+      error.name === 'TimeoutError' || (error.name === 'AbortError' && timeoutSignal.aborted)
+    );
+    const isParseError = error instanceof SyntaxError;
+    return buildResult({
+      providerId: 'cline-pass',
+      providerName: 'ClinePass',
+      ok: false,
+      configured: true,
+      error: isTimeout
+        ? 'Request timed out'
+        : isParseError
+          ? 'Invalid response from provider'
+          : (error instanceof Error ? error.message : 'Request failed'),
+    });
+  }
+};
+
 const DEEPSEEK_QUOTA_URL = 'https://api.deepseek.com/user/balance';

 const fetchDeepseekQuota = async (): Promise<ProviderResult> => {
@@ -3068,6 +3190,8 @@ const fetchQuotaForProviderUncoalesced = async (providerId: string): Promise<Pro
      return fetchCursorQuota();
    case 'crof':
      return fetchCrofQuota();
+    case 'cline-pass':
+      return fetchClinePassQuota();
    case 'deepseek':
      return fetchDeepseekQuota();
    case 'hyper':