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
@@ -23,6 +23,7 @@ These provider IDs are currently dispatchable via `fetchQuotaForProvider(provide
 | Provider ID | Display name | Module | Auth aliases/keys |
 | --- | --- | --- | --- |
 | `claude` | Claude | `providers/claude/` | Claude Code Keychain entry, Claude Code credentials file, OpenCode `auth.json` (`anthropic`, `claude`), `CLAUDE_CODE_OAUTH_TOKEN` |
+| `cline-pass` | ClinePass | `providers/cline-pass.js` | `cline-pass` (API key under `key` or `token`) |
 | `codex` | Codex | `providers/codex.js` | `openai`, `codex`, `chatgpt` |
 | `command-code` | Command Code | `providers/command-code.js` | `command-code` OAuth/API credential in OpenCode `auth.json`, or `COMMAND_CODE_API_KEY` |
 | `cursor` | Cursor | `providers/cursor.js` | Environment/token files, OpenChamber-managed credentials, or explicit one-time Cursor import |
@@ -96,6 +97,16 @@ In 2025/2026 MiniMax rebranded "Coding Plan" to "Token Plan" alongside the M3 mo
 - **model_remains array**: Now contains entries for multiple model categories (chat, speech, video, image). The provider selects the chat-model entry by matching `MiniMax-M*`, then `general`/`chat`/`text` by name, then any entry with a remaining percent.
 - **Window status**: The `current_interval_status` and `current_weekly_status` fields indicate whether a window is active. Status `3` means the window is not applicable for the current plan tier (e.g. legacy plans without weekly limits). The provider omits inactive windows.

+## ClinePass quota semantics
+
+ClinePass reads `data.limits` from its usage-limits endpoint. Web/Electron and
+VS Code accept only known window types with finite numeric or non-empty numeric
+string percentages. Invalid windows are skipped independently; no usable windows
+is a failed refresh, not zero usage. Both implementations choose a non-empty
+`key`, then `token`, and expose auth/fetch dependencies for focused tests.
+Saved UI provider-visibility lists remain authoritative; installations without a
+saved list include ClinePass through the provider registry.
+
 ## Charm Hyper balance semantics

 `GET https://hyper.charm.land/v1/credits` returns a team's current Hypercredit balance, not a percentage or reset timestamp. The [Hyper FAQ](https://hyper.charm.land/faq) defines one Hypercredit as $0.05. Both runtimes expose `credits_balance` in dollars and `credits` as a numeric label under the UI's localized window title. Keep English unit text out of that numeric label.
@@ -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,