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
@@ -0,0 +1,125 @@
+import { readAuthFile } from '../../opencode/auth.js';
+import {
+  getAuthEntry,
+  normalizeAuthEntry,
+  asObject,
+  asNonEmptyString,
+  buildResult,
+  toUsageWindow,
+  toNumber,
+  toTimestamp
+} from '../utils/index.js';
+
+export const providerId = 'cline-pass';
+export const providerName = 'ClinePass';
+export const aliases = ['cline-pass'];
+const CLINE_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 WINDOW_KINDS = new Map([
+  ['five_hour', { key: '5h', windowSeconds: 5 * 60 * 60 }],
+  ['weekly', { key: 'weekly', windowSeconds: 7 * 24 * 60 * 60 }],
+  ['monthly', { key: 'monthly', windowSeconds: null }]
+]);
+
+const getApiKey = (auth) => {
+  const entry = normalizeAuthEntry(getAuthEntry(auth, aliases));
+  return asNonEmptyString(entry?.key) ?? asNonEmptyString(entry?.token);
+};
+
+export const isConfigured = (auth = readAuthFile()) => Boolean(getApiKey(auth));
+
+export const fetchQuota = async ({ readAuth = readAuthFile, fetchImpl = fetch } = {}) => {
+  const apiKey = getApiKey(readAuth());
+
+  if (!apiKey) {
+    return buildResult({
+      providerId,
+      providerName,
+      ok: false,
+      configured: false,
+      error: 'Not configured'
+    });
+  }
+
+  const timeoutSignal = AbortSignal.timeout(15_000);
+
+  try {
+    const response = await fetchImpl(CLINE_USAGE_URL, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Accept-Encoding': 'identity'
+      },
+      signal: timeoutSignal
+    });
+
+    if (!response.ok) {
+      return buildResult({
+        providerId,
+        providerName,
+        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 = {};
+    for (const item of limits) {
+      const limit = asObject(item);
+      if (!limit) continue;
+      const kind = WINDOW_KINDS.get(asNonEmptyString(limit.type));
+      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,
+        providerName,
+        ok: false,
+        configured: true,
+        error: 'No quota data in response'
+      });
+    }
+
+    return buildResult({
+      providerId,
+      providerName,
+      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,
+      providerName,
+      ok: false,
+      configured: true,
+      error: isTimeout
+        ? 'Request timed out'
+        : isParseError
+          ? 'Invalid response from provider'
+          : (error instanceof Error ? error.message : 'Request failed')
+    });
+  }
+};
@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'vitest';
+import { fetchQuota, isConfigured } from './cline-pass.js';
+
+const readAuth = () => ({ 'cline-pass': { key: 'test-token' } });
+
+// Response shape verified by the contributor against the live ClinePass API.
+const documentedPayload = {
+  data: { limits: [
+    { type: 'five_hour', percentUsed: 43, resetsAt: '2026-09-08T17:00:44.598174595Z' },
+    { type: 'weekly', percentUsed: 17 },
+    { type: 'monthly', percentUsed: 8 },
+  ] },
+  success: true,
+};
+
+describe('ClinePass quota provider', () => {
+  it('maps the documented windows and sends credentials only in headers', async () => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async (url, options) => {
+      expect(url).toBe('https://api.cline.bot/api/v1/users/me/plan/usage-limits');
+      expect(new Headers(options.headers).get('Authorization')).toBe('Bearer test-token');
+      expect(options.signal).toBeInstanceOf(AbortSignal);
+      return Response.json(documentedPayload);
+    } });
+    expect(result.ok).toBe(true);
+    expect(result.providerId).toBe('cline-pass');
+    expect(Object.keys(result.usage.windows)).toEqual(['5h', 'weekly', 'monthly']);
+    expect(result.usage.windows['5h'].usedPercent).toBe(43);
+    expect(result.usage.windows['5h'].remainingPercent).toBe(57);
+    expect(result.usage.windows['5h'].windowSeconds).toBe(18_000);
+    expect(result.usage.windows['5h'].resetAt).toBe(Date.parse('2026-09-08T17:00:44.598174595Z'));
+    expect(result.usage.windows.weekly.usedPercent).toBe(17);
+    expect(result.usage.windows.weekly.windowSeconds).toBe(604_800);
+    expect(result.usage.windows.monthly.usedPercent).toBe(8);
+    expect(result.usage.windows.monthly.windowSeconds).toBeNull();
+    expect(JSON.stringify(result)).not.toContain('test-token');
+  });
+
+  it.each([0, '0', '51'])('accepts finite percentage %s', async (percentUsed) => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => Response.json({ data: { limits: [{ type: 'weekly', percentUsed }] } }) });
+    expect(result.ok).toBe(true);
+    expect(result.usage.windows.weekly.usedPercent).toBe(Number(percentUsed));
+  });
+
+  it.each([
+    { type: 'constructor', percentUsed: 5 }, { type: 'toString', percentUsed: 5 },
+    { type: '__proto__', percentUsed: 5 }, { type: 'quarterly', percentUsed: 5 },
+    { type: 'weekly', percentUsed: '' }, { type: 'weekly', percentUsed: ' ' },
+    { type: 'weekly', percentUsed: null }, { type: 'weekly', percentUsed: true },
+    { type: 'weekly', percentUsed: 'NaN' }, null,
+  ])('ignores malformed windows without discarding valid siblings: %j', async (limit) => {
+    const invalid = await fetchQuota({ readAuth, fetchImpl: async () => Response.json({ data: { limits: [limit] } }) });
+    expect(invalid.ok).toBe(false);
+    expect(invalid.configured).toBe(true);
+    expect(invalid.usage).toBeNull();
+    const mixed = await fetchQuota({ readAuth, fetchImpl: async () => Response.json({ data: { limits: [limit, { type: 'monthly', percentUsed: 8 }] } }) });
+    expect(mixed.ok).toBe(true);
+    expect(Object.keys(mixed.usage.windows)).toEqual(['monthly']);
+  });
+
+  it.each([null, [], {}, { data: null }, { data: { limits: [] } }])('rejects empty or malformed payload %j', async (payload) => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => Response.json(payload) });
+    expect(result.ok).toBe(false);
+    expect(result.usage).toBeNull();
+    expect(result.error).toBe('No quota data in response');
+  });
+
+  it.each([{ key: '' }, { key: ' ' }, { key: 42 }, {}])('uses a usable token when the key is malformed: %j', async (entry) => {
+    const auth = { 'cline-pass': { ...entry, token: 'test-token' } };
+    expect(isConfigured(auth)).toBe(true);
+    const result = await fetchQuota({ readAuth: () => auth, fetchImpl: async (_url, options) => {
+      expect(new Headers(options.headers).get('Authorization')).toBe('Bearer test-token');
+      return Response.json(documentedPayload);
+    } });
+    expect(result.ok).toBe(true);
+  });
+
+  it.each([{}, { 'cline-pass': { key: '' } }, { 'cline-pass': { key: 42 } }])('does not fetch without usable credentials: %j', async (auth) => {
+    expect(isConfigured(auth)).toBe(false);
+    const result = await fetchQuota({ readAuth: () => auth, fetchImpl: async () => { throw new Error('Unexpected fetch'); } });
+    expect(result.configured).toBe(false);
+    expect(result.error).toBe('Not configured');
+  });
+
+  it.each([[401, 'Session expired — please re-authenticate with ClinePass'], [503, 'API error: 503']])('reports HTTP %s', async (status, error) => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => new Response(null, { status }) });
+    expect(result.ok).toBe(false);
+    expect(result.usage).toBeNull();
+    expect(result.error).toBe(error);
+  });
+
+  it('reports invalid JSON', async () => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => new Response('{') });
+    expect(result.error).toBe('Invalid response from provider');
+  });
+
+  it('recognizes the timeout exception from AbortSignal.timeout', async () => {
+    const result = await fetchQuota({ readAuth, fetchImpl: async () => { throw new DOMException('Timed out', 'TimeoutError'); } });
+    expect(result.ok).toBe(false);
+    expect(result.configured).toBe(true);
+    expect(result.usage).toBeNull();
+    expect(result.error).toBe('Request timed out');
+  });
+});
@@ -8,6 +8,7 @@
 import { buildResult } from '../utils/index.js';

 import * as claude from './claude/index.js';
+import * as clinePass from './cline-pass.js';
 import * as codex from './codex.js';
 import * as copilot from './copilot.js';
 import * as crof from './crof.js';
@@ -37,6 +38,12 @@ const registry = {
    isConfigured: claude.isConfigured,
    fetchQuota: claude.fetchQuota
  },
+  'cline-pass': {
+    providerId: clinePass.providerId,
+    providerName: clinePass.providerName,
+    isConfigured: clinePass.isConfigured,
+    fetchQuota: clinePass.fetchQuota
+  },
  codex: {
    providerId: codex.providerId,
    providerName: codex.providerName,