@astrosheep/pi-quota 0.5.7 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # @astrosheep/pi-quota
 
-Compact quota status for Pi: Codex, Kimi, OpenCode Go and DeepSeek work out of the box; new-api and Sub2API use explicit provider bindings.
+Compact quota status for Pi: Codex, Kimi, OpenCode Go and DeepSeek work out of the box; new-api, Sub2API and YesCode use explicit provider bindings.
 
 ```bash
 pi install npm:@astrosheep/pi-quota
@@ -30,7 +30,9 @@ Add bindings in global `~/.pi/agent/settings.json` under `quotaUsage` (not proje
     "providers": {
       "my-sub2api": { "adapter": "sub2api" },
       "my-new-api": { "adapter": "new-api", "quotaPerUnit": 500000, "currency": "USD" },
-      "deepseek": { "adapter": "deepseek" }
+      "deepseek": { "adapter": "deepseek" },
+      "opencode-go-2": { "adapter": "opencode-go" },
+      "yes-vg": { "adapter": "yescode", "username": "you@example.com", "password": "..." }
     }
   }
 }
@@ -43,11 +45,17 @@ Use the **exact Pi provider ID**. Built-in providers and explicitly bound provid
 | `sub2api` | `{baseUrl}/usage` | Wallet, key quota, rate windows or subscription day/week/month windows; API-key Today/Lifetime actual spend |
 | `new-api` | Account PAT `/api/user/self`, falling back to key-native billing/token endpoints | Account balance + lifetime spend; finite key quota when explicitly granted; **not** a renewable window |
 | `deepseek` | Official `/user/balance` | Balance only; no invented spend |
+| `opencode-go` | Official `https://opencode.ai/zen/go/v1/usage` | 5h/1w/30d windows, same as the built-in `opencode-go` adapter |
+| `yescode` | `co.yes.vg` login → session → `/api/v1/auth/profile` + `/api/v1/user/balance` | Wallet (subscription + pay-as-you-go) plus daily/weekly subscription windows |
+
+Bind `opencode-go` to a second OpenCode Go account: register it as its own Pi provider in `models.json` with its own `apiKey` (e.g. `opencode-go-2`), then bind that ID here. The built-in `opencode-go` binding is implicit and needs no entry; the reserved IDs `openai-codex`, `kimi-coding` and `opencode-go` cannot be rebound.
 
 Sub2API accepts no extra settings; it preserves deployment subpaths. Rate-only keys need not expose a top-level currency (rates are USD). Unknown rate-window durations and invalid limits fail rather than inventing a 1d window. Subscription periods without a cap are omitted. Its dashboard `/api/v1/usage` is a separate, JWT-authenticated paginated request log; the adapter uses the API-key `/v1/usage` instead.
 
 For new-api, `quotaPerUnit` defaults to `500000`, `currency` to `USD`. Optionally add `dashboardAccessToken` (console system access token) and `dashboardUserId` (positive numeric ID required by some old forks) to that provider. This PAT is the **only** optional secret kept in settings. The account endpoint takes precedence; failures fall back to the key-native billing and token usage paths. Without a PAT, an API key cannot read the dashboard account quota. A finite key reports a quota bar only when `total_granted` is present and consistent with used plus remaining; otherwise it shows a balance and lifetime spend, without inventing a limit. Values in settings and server error bodies are never logged.
 
+For YesCode, `username` is the account email and `password` the account password; both stay in global `settings.json`, which is the trade-off of this adapter. YesCode rejects API keys on account endpoints ("requires a user session or JWT"), so the adapter logs in via `/api/v1/auth/login`, caches the issued cookie/JWT in memory for ~23 hours, and re-logs in once on an auth failure. The model `cr_` key is never sent to account endpoints; it only pins the provider to the official `co.yes.vg` origin. Balances are summed from subscription and pay-as-you-go; daily/weekly windows appear only when the account actually has those caps.
+
 Authenticated quota URLs must use HTTPS, except HTTP loopback for local deployments. URL userinfo, query strings, fragments and HTTP redirects are rejected; credentials never follow redirects. Fixed official endpoints reject custom origins. No browser cookie scraping or credential discovery.
 
 ## Architecture

package/examples/settings.fragment.json

@@ -10,6 +10,11 @@
     },
     "my-sub2api": {
       "adapter": "sub2api"
+    },
+    "yes-vg": {
+      "adapter": "yescode",
+      "username": "you@example.com",
+      "password": "your-account-password"
     }
   }
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@astrosheep/pi-quota",
-  "version": "0.5.7",
+  "version": "0.7.0",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "description": "Composable quota bar with Codex, Kimi, OpenCode Go, new-api, DeepSeek and Sub2API adapters",
+  "description": "Composable quota bar with Codex, Kimi, OpenCode Go, new-api, DeepSeek, Sub2API and YesCode adapters",
   "keywords": [
     "pi-package"
   ],

package/src/bar/card.ts

@@ -65,7 +65,7 @@ function gridRows(states: readonly Exclude<QuotaState, { kind: 'loading' }>[], n
             group, kind: 'quota',
             provider: index === 0 ? state.label : '',
             metric: `${window.scope ? `${window.scope}/` : ''}${window.label}`,
-            value: `${horizontalBar(remaining, barWidth)} ${formatPercent(remaining)}`,
+            value: `${horizontalBar(remaining, barWidth)} ${padStartVisible(formatPercent(remaining), 4)}`,
             secondary: `↺ ${window.resetAt === null ? '?' : duration(window.resetAt - now)}`,
             valueTone: remainingTone(remaining), metricTone: 'dim', secondaryTone: 'dim',
           });
@@ -125,7 +125,7 @@ export function aggregateUsageLines(
     previousGroup = row.group;
     const provider = padEndVisible(row.provider, providerWidth);
     const metric = row.kind === 'quota' ? padEndVisible(row.metric, metricWidth) : '';
-    const value = padStartVisible(row.value, row.kind === 'quota' ? quotaValueWidth : otherValueWidth);
+    const value = padEndVisible(row.value, row.kind === 'quota' ? quotaValueWidth : otherValueWidth);
     const line = paint('text', provider)
       + (metric ? paint(row.metricTone, `  ${metric}`) : '')
       + paint(row.valueTone, `  ${value}`)

package/src/config.ts

@@ -1,12 +1,16 @@
 import { createDeepSeekAdapter } from './query/deepseek.ts';
 import { createNewApiAdapter, validateNewApiOptions } from './query/new-api.ts';
+import { createOpenCodeGoAdapter } from './query/opencode-go.ts';
 import { createSub2ApiAdapter } from './query/sub2api.ts';
+import { createYesCodeAdapter, validateYesCodeOptions } from './query/yescode.ts';
 import type { NewApiOptions } from './query/new-api.ts';
+import type { YesCodeOptions } from './query/yescode.ts';
 import type { QuotaAdapter } from './query/types.ts';
 
 export type ProviderQuotaConfig =
   | ({ adapter: 'new-api'; quotaPerUnit: number; currency: string } & Pick<NewApiOptions, 'dashboardAccessToken' | 'dashboardUserId'>)
-  | { adapter: 'deepseek' | 'sub2api' };
+  | ({ adapter: 'yescode' } & YesCodeOptions)
+  | { adapter: 'deepseek' | 'sub2api' | 'opencode-go' };
 export interface QuotaConfig { providers: Record<string, ProviderQuotaConfig> }
 
 const DASHBOARD_KEYS = ['dashboardAccessToken', 'dashboardUserId'] as const;
@@ -28,7 +32,7 @@ function parseDashboardOptions(item: Record<string, unknown>): Pick<NewApiOption
 export class QuotaConfigError extends Error {
   constructor() {
     // Settings may accidentally contain secrets. Never echo content/values.
-    super('Invalid settings.json quotaUsage. Use providers with adapter "new-api", "deepseek" or "sub2api".');
+    super('Invalid settings.json quotaUsage. Use providers with adapter "new-api", "deepseek", "sub2api", "opencode-go" or "yescode".');
   }
 }
 
@@ -49,9 +53,18 @@ export function parseQuotaConfig(value: unknown): QuotaConfig {
       providers[provider] = { adapter: 'deepseek' };
       continue;
     }
-    if (item.adapter === 'sub2api') {
+    if (item.adapter === 'sub2api' || item.adapter === 'opencode-go') {
       if (Object.keys(item).length !== 1) throw new QuotaConfigError();
-      providers[provider] = { adapter: 'sub2api' };
+      providers[provider] = { adapter: item.adapter };
+      continue;
+    }
+    if (item.adapter === 'yescode') {
+      if (Object.keys(item).some(key => !['adapter', 'username', 'password'].includes(key))
+        || typeof item.username !== 'string' || typeof item.password !== 'string') throw new QuotaConfigError();
+      try {
+        providers[provider] = { adapter: 'yescode',
+          ...validateYesCodeOptions({ username: item.username, password: item.password }) };
+      } catch { throw new QuotaConfigError(); }
       continue;
     }
     if (item.adapter !== 'new-api'
@@ -73,6 +86,8 @@ export function loadQuotaAdaptersFromSettings(settings: unknown): QuotaAdapter[]
     switch (options.adapter) {
       case 'deepseek': return createDeepSeekAdapter(provider);
       case 'sub2api': return createSub2ApiAdapter(provider);
+      case 'opencode-go': return createOpenCodeGoAdapter(provider);
+      case 'yescode': return createYesCodeAdapter(provider, options);
       case 'new-api': return createNewApiAdapter(provider, options);
     }
   });

package/src/extension.ts

@@ -7,13 +7,16 @@ import { createDeepSeekAdapter } from './query/deepseek.ts';
 import { kimiAdapter } from './query/kimi.ts';
 import { openCodeGoAdapter } from './query/opencode-go.ts';
 import { QuotaController } from './query/controller.ts';
-import { createJsonClient } from './query/http.ts';
+import { createJsonClient, createPostJsonClient } from './query/http.ts';
 import { AdapterRegistry } from './query/registry.ts';
 import type { ProviderAuth, QuotaAdapter, QuotaState } from './query/types.ts';
 
 export const STATUS_EVENT = 'quota-bar:state:v1';
 const STATUS_KEY = 'quota-bar';
 const USAGE_WIDGET = 'quota-bar:usage';
+const REFRESHING_TEXT = 'Refreshing…';
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export const SPINNER_INTERVAL_MS = 80;
 
 export interface QuotaExtensionOptions {
   // Explicit adapters replace matching built-ins; duplicate explicit IDs are rejected.
@@ -39,6 +42,8 @@ export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
     let lastStatus: string | undefined;
     // Invalidates pending commands on model/session replacement or another /usage.
     let commandGeneration = 0;
+    // Tracks whether /usage has already produced a snapshot in this runtime.
+    let hasUsageSnapshot = false;
 
     pi.registerEntryRenderer<UsageCard>(USAGE_ENTRY, (entry, _options, theme) => {
       const paint = process.env.NO_COLOR !== undefined ? undefined
@@ -68,9 +73,10 @@ export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
     };
 
     const getJson = createJsonClient();
+    const postJson = createPostJsonClient();
 
     const controller = new QuotaController({
-      registry, getJson, intervalMs: options.intervalMs, timeoutMs: options.timeoutMs,
+      registry, getJson, postJson, intervalMs: options.intervalMs, timeoutMs: options.timeoutMs,
       onState(state) {
         paintFooter();
         pi.events.emit(STATUS_EVENT, state); // Structured data, no credentials or ANSI.
@@ -123,7 +129,7 @@ export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
         return controller.state;
       }
       const scratch = new QuotaController({
-        registry, getJson, intervalMs: options.intervalMs, timeoutMs: options.timeoutMs,
+        registry, getJson, postJson, intervalMs: options.intervalMs, timeoutMs: options.timeoutMs,
         onState() {},
       });
       scratch.select(provider);
@@ -175,7 +181,35 @@ export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
         if (!ctx.hasUI) return;
         bind(ctx);
         const generation = ++commandGeneration;
-        if (ctx.mode === 'tui') ctx.ui.setWidget(USAGE_WIDGET, ['Quota …']);
+        let spinner: ReturnType<typeof setInterval> | undefined;
+        if (ctx.mode === 'tui') {
+          // Previous snapshots are already rendered in the transcript. Only add the
+          // spinner here, otherwise refreshing duplicates the last grid in a widget.
+          const label = hasUsageSnapshot ? REFRESHING_TEXT : 'Fetching quota…';
+          let frame = 0;
+          const paintSpinner = () => {
+            if (!current || generation !== commandGeneration) return false;
+            const spinnerLine = `${SPINNER_FRAMES[frame]} ${label}`;
+            ctx.ui.setWidget(USAGE_WIDGET, (_tui, theme) => {
+              const paint = process.env.NO_COLOR !== undefined ? undefined
+                : (tone: Parameters<typeof theme.fg>[0], text: string) => theme.fg(tone, text);
+              return {
+                render(width: number): string[] {
+                  if (width < spinnerLine.length) return [];
+                  return [paint ? paint('dim', spinnerLine) : spinnerLine];
+                },
+                invalidate() {},
+              };
+            });
+            return true;
+          };
+          paintSpinner();
+          spinner = setInterval(() => {
+            frame = (frame + 1) % SPINNER_FRAMES.length;
+            if (!paintSpinner() && spinner) { clearInterval(spinner); spinner = undefined; }
+          }, SPINNER_INTERVAL_MS);
+          spinner.unref?.();
+        }
         try {
           const getAuth = resolveAuth(ctx);
           const providers = supportedProviders(ctx);
@@ -195,12 +229,14 @@ export function createQuotaExtension(options: QuotaExtensionOptions = {}) {
           const visibleStates = args.trim() === '--all'
             ? ordered : ordered.filter(state => state.kind === 'ready');
           const card = captureAllUsage(visibleStates);
+          hasUsageSnapshot = true;
           pi.appendEntry<UsageCard>(USAGE_ENTRY, card);
           // Custom entry renderers are TUI-only; RPC clients still get readable output.
           if (ctx.mode !== 'tui') {
             ctx.ui.notify(usageLines(card, undefined).join('\n'), 'info');
           }
         } finally {
+          if (spinner) { clearInterval(spinner); spinner = undefined; }
           // An older request must not clear a newer command's loading indicator.
           if (current && generation === commandGeneration && ctx.mode === 'tui') {
             ctx.ui.setWidget(USAGE_WIDGET, undefined);

package/src/query/controller.ts

@@ -6,6 +6,7 @@ type AuthResolver = QueryContext['getAuth'];
 interface ControllerOptions {
   registry: AdapterRegistry;
   getJson: QueryContext['getJson'];
+  postJson: QueryContext['postJson'];
   onState(state: QuotaState): void;
   now?: () => number;
   intervalMs?: number;
@@ -89,7 +90,7 @@ export class QuotaController {
         abort.signal.throwIfAborted();
         const result = await abortable(adapter.query({
           provider: adapter.provider, signal: abort.signal, now: this.now,
-          getAuth, getJson: this.options.getJson,
+          getAuth, getJson: this.options.getJson, postJson: this.options.postJson,
         }), abort.signal);
         if (!active()) return;
         const snapshot = validateSnapshot(result);

package/src/query/http.ts

@@ -52,6 +52,60 @@ export function createJsonClient(fetcher: typeof fetch = globalThis.fetch): Quer
   };
 }
 
+export function createPostJsonClient(fetcher: typeof fetch = globalThis.fetch): QueryContext['postJson'] {
+  return async (url, body, headers, signal) => {
+    try {
+      const response = await fetcher(url, {
+        method: 'POST',
+        headers: { Accept: 'application/json', 'Content-Type': 'application/json', ...headers },
+        body: JSON.stringify(body),
+        signal, redirect: 'error', // Never forward credentials to a redirected endpoint.
+      });
+      if (!response.ok) {
+        const retry = response.headers.get('retry-after');
+        const seconds = retry && /^\d+(\.\d+)?$/.test(retry) ? Number(retry) : NaN;
+        const delay = Number.isFinite(seconds) ? seconds * 1000
+          : retry ? Date.parse(retry) - Date.now() : NaN;
+        await response.body?.cancel();
+        if (response.status === 401 || response.status === 403) throw new QuotaError('auth');
+        if (response.status === 429) {
+          throw new QuotaError('rate-limit', Number.isFinite(delay) ? Math.max(0, delay) : undefined);
+        }
+        throw new QuotaError('http');
+      }
+      const setCookie = typeof response.headers.getSetCookie === 'function'
+        ? response.headers.getSetCookie() : [];
+      const reader = response.body?.getReader();
+      if (!reader) throw new QuotaError('schema');
+      const chunks: Uint8Array[] = [];
+      let size = 0;
+      try {
+        while (true) {
+          const part = await reader.read();
+          if (part.done) break;
+          size += part.value.length;
+          if (size > 256 * 1024) {
+            await reader.cancel();
+            throw new QuotaError('schema');
+          }
+          chunks.push(part.value);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+      try {
+        return { body: JSON.parse(Buffer.concat(chunks).toString('utf8')) as unknown, setCookie };
+      } catch {
+        throw new QuotaError('schema');
+      }
+    } catch (error) {
+      if (error instanceof QuotaError) throw error;
+      if (signal.aborted) throw signal.reason;
+      throw new QuotaError('network');
+    }
+  };
+}
+
 export function header(auth: ProviderAuth, name: string): string | undefined {
   return Object.entries(auth.headers ?? {}).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
 }

package/src/query/opencode-go.ts

@@ -30,13 +30,20 @@ export function parseOpenCodeGo(payload: unknown): QuotaWindow[] {
   return windows;
 }
 
-export const openCodeGoAdapter: QuotaAdapter = {
-  provider: 'opencode-go', label: 'OpenCode Go',
-  async query(context) {
-    const auth = await officialAuth(context, 'https://opencode.ai');
-    const data = await context.getJson('https://opencode.ai/zen/go/v1/usage', {
-      Authorization: `Bearer ${bearer(auth)}`,
-    }, context.signal);
-    return { windows: parseOpenCodeGo(data), fetchedAt: context.now() };
-  },
-};
+// A second OpenCode Go account is just another Pi provider ID (configured in
+// models.json with its own apiKey); auth and endpoint stay official regardless.
+export function createOpenCodeGoAdapter(provider: string): QuotaAdapter {
+  return {
+    provider,
+    label: provider === 'opencode-go' ? 'OpenCode Go' : `OpenCode Go (${provider})`,
+    async query(context) {
+      const auth = await officialAuth(context, 'https://opencode.ai');
+      const data = await context.getJson('https://opencode.ai/zen/go/v1/usage', {
+        Authorization: `Bearer ${bearer(auth)}`,
+      }, context.signal);
+      return { windows: parseOpenCodeGo(data), fetchedAt: context.now() };
+    },
+  };
+}
+
+export const openCodeGoAdapter = createOpenCodeGoAdapter('opencode-go');

package/src/query/types.ts

@@ -42,12 +42,18 @@ export interface ProviderAuth {
   baseUrl?: string;
 }
 
+export interface PostJsonResult {
+  body: unknown;
+  setCookie: string[];
+}
+
 export interface QueryContext {
   provider: string;
   signal: AbortSignal;
   now(): number;
   getAuth(provider: string): Promise<ProviderAuth | undefined>;
   getJson(url: string, headers: Record<string, string>, signal: AbortSignal): Promise<unknown>;
+  postJson(url: string, body: unknown, headers: Record<string, string>, signal: AbortSignal): Promise<PostJsonResult>;
 }
 
 export interface QuotaAdapter {

package/src/query/yescode.ts

@@ -0,0 +1,176 @@
+import { officialAuth } from './http.ts';
+import { numeric, object, percent, timestamp, windowLabel } from './parse.ts';
+import { QuotaError } from './types.ts';
+import type { PostJsonResult, QuotaAdapter, QuotaSnapshot, QuotaWindow } from './types.ts';
+
+export const YESCODE_ORIGIN = 'https://co.yes.vg';
+
+// co.yes.vg rejects API keys on account endpoints ("requires a user session or
+// JWT"). Login is the only way in; the issued cookie/JWT lives ~24h, so cache
+// it in memory and re-login on auth failure. The model cr_ key is never sent
+// to account endpoints — officialAuth only pins the origin and proves the
+// provider exists in Pi auth.
+export interface YesCodeOptions {
+  username: string; // Login takes the account username (email also works).
+  password: string;
+}
+
+interface YesCodeSession {
+  headers: Record<string, string>;
+  expiresAt: number;
+}
+
+const SESSION_TTL_MS = 23 * 3600 * 1000; // observed cookie Max-Age is 24h
+
+export function validateYesCodeOptions(options: YesCodeOptions): YesCodeOptions {
+  const { username, password } = options;
+  if (typeof username !== 'string' || username.trim() === '') {
+    throw new Error('username must be a non-empty string');
+  }
+  if (typeof password !== 'string' || password === '') throw new Error('password must be a non-empty string');
+  return { username, password };
+}
+
+function cookieValue(setCookie: readonly string[], name: string): string | undefined {
+  for (const entry of setCookie) {
+    if (!entry.startsWith(`${name}=`)) continue;
+    const value = entry.slice(name.length + 1).split(';', 1)[0]!;
+    if (value !== '' && !/[\s;]/.test(value)) return value;
+  }
+  return undefined;
+}
+
+// POST /api/v1/auth/login returns {token} and sets yescode_auth/yescode_csrf.
+// The cookie pair is what the web app itself uses; the bare JWT is the
+// documented UserToken fallback (Authorization: Bearer).
+export function parseYesCodeLogin(result: PostJsonResult, now: number): YesCodeSession {
+  const auth = cookieValue(result.setCookie, 'yescode_auth');
+  if (auth) {
+    const csrf = cookieValue(result.setCookie, 'yescode_csrf');
+    return { headers: { Cookie: csrf ? `yescode_auth=${auth}; yescode_csrf=${csrf}` : `yescode_auth=${auth}` },
+      expiresAt: now + SESSION_TTL_MS };
+  }
+  const token = object(result.body).token;
+  if (typeof token !== 'string' || token.trim() === '' || /[\s;]/.test(token)) throw new QuotaError('schema');
+  return { headers: { Authorization: `Bearer ${token}` }, expiresAt: now + SESSION_TTL_MS };
+}
+
+// Balances may legitimately be negative (debt); limits/spends may not.
+function optionalAmount(value: unknown): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const result = numeric(value);
+  if (result === null) throw new QuotaError('schema');
+  return result;
+}
+
+function nonNegative(value: unknown): number | undefined {
+  const result = optionalAmount(value);
+  if (result !== undefined && result < 0) throw new QuotaError('schema');
+  return result;
+}
+
+function limitWindow(id: string, label: string, durationSeconds: number,
+  limitRaw: unknown, usedRaw: unknown, resetAt: number | null): QuotaWindow[] {
+  const used = nonNegative(usedRaw); // validate present-but-corrupt spends even without a cap
+  const limit = nonNegative(limitRaw);
+  if (limit === undefined || limit === 0) return []; // no configured cap: nothing to draw
+  if (used === undefined) {
+    return [{ id, label, durationSeconds, remainingPercent: null, resetAt }];
+  }
+  const remaining = Math.max(0, limit - used);
+  return [{ id, label, durationSeconds, remainingPercent: percent(remaining / limit * 100), resetAt,
+    amounts: { currency: 'USD', limit, used, remaining } }];
+}
+
+// GET /api/v1/user/balance (optional; some accounts may lack it) merged with
+// GET /api/v1/auth/profile (required). The live response carries a generic
+// spending_limits array (scope/spent/limit/remaining/resets_at/window_seconds)
+// plus top-level weekly_* and monthly_* fields; profile is the last fallback.
+function spendingLimitWindows(balanceData: Record<string, unknown>): QuotaWindow[] | null {
+  if (balanceData.spending_limits === undefined) return null;
+  if (!Array.isArray(balanceData.spending_limits)) throw new QuotaError('schema');
+  const windows = balanceData.spending_limits.flatMap((entry): QuotaWindow[] => {
+    const item = object(entry);
+    const limit = nonNegative(item.limit);
+    const spent = nonNegative(item.spent);
+    const remaining = nonNegative(item.remaining);
+    const windowSeconds = numeric(item.window_seconds);
+    const resetAt = timestamp(item.resets_at);
+    if (typeof item.key !== 'string' || item.key === ''
+      || windowSeconds === null || !Number.isSafeInteger(windowSeconds) || windowSeconds <= 0) {
+      throw new QuotaError('schema');
+    }
+    if (limit === undefined || limit === 0) return []; // uncapped: nothing to draw
+    if (spent === undefined) {
+      return [{ id: `spending:${item.key}`, label: windowLabel(windowSeconds), durationSeconds: windowSeconds,
+        remainingPercent: null, resetAt }];
+    }
+    const left = remaining ?? Math.max(0, limit - spent);
+    return [{ id: `spending:${item.key}`, label: windowLabel(windowSeconds), durationSeconds: windowSeconds,
+      remainingPercent: percent(left / limit * 100), resetAt,
+      amounts: { currency: 'USD', limit, used: spent, remaining: left } }];
+  });
+  // Footer/detail convention is ascending duration (5h → 1w → 30d).
+  return windows.sort((a, b) => a.durationSeconds - b.durationSeconds);
+}
+
+export function parseYesCodeAccount(balancePayload: unknown, profilePayload: unknown): Omit<QuotaSnapshot, 'fetchedAt'> {
+  const balanceData = object(balancePayload);
+  const profile = object(profilePayload);
+  const plan = object(profile.subscription_plan);
+  const subscription = optionalAmount(balanceData.subscription_balance ?? profile.subscription_balance);
+  const paygo = optionalAmount(balanceData.pay_as_you_go_balance ?? profile.pay_as_you_go_balance);
+  if (subscription === undefined && paygo === undefined) throw new QuotaError('schema');
+
+  const weekStart = timestamp(profile.last_week_reset);
+  const monthStart = timestamp(profile.last_month_reset);
+  const windows = spendingLimitWindows(balanceData) ?? [
+    ...limitWindow('daily', '1d', 86400, balanceData.daily_limit, balanceData.daily_spent,
+      timestamp(balanceData.daily_resets_at ?? balanceData.daily_reset_at)),
+    ...limitWindow('weekly', '1w', 604800, balanceData.weekly_limit ?? plan.weekly_limit,
+      balanceData.weekly_spent_balance ?? balanceData.weekly_spent ?? profile.current_week_spend,
+      timestamp(balanceData.weekly_resets_at ?? balanceData.weekly_reset_at)
+        ?? (weekStart === null ? null : weekStart + 604800000)),
+    ...limitWindow('monthly', '30d', 2592000, balanceData.monthly_spend_limit ?? plan.monthly_spend_limit,
+      balanceData.monthly_spent_balance ?? balanceData.monthly_spent ?? profile.current_month_spend,
+      timestamp(balanceData.monthly_resets_at ?? balanceData.monthly_reset_at)
+        ?? (monthStart === null ? null : monthStart + 2592000000)),
+  ];
+  return { windows, balance: { currency: 'USD', remaining: (subscription ?? 0) + (paygo ?? 0) } };
+}
+
+export function createYesCodeAdapter(provider: string, options: YesCodeOptions): QuotaAdapter {
+  const credentials = validateYesCodeOptions(options);
+  let session: YesCodeSession | undefined;
+  return {
+    provider, label: provider,
+    async query(context) {
+      await officialAuth(context, YESCODE_ORIGIN);
+      const login = async (): Promise<YesCodeSession> => parseYesCodeLogin(await context.postJson(
+        `${YESCODE_ORIGIN}/api/v1/auth/login`,
+        { username: credentials.username, password: credentials.password },
+        { Origin: YESCODE_ORIGIN, Referer: `${YESCODE_ORIGIN}/login` }, context.signal), context.now());
+      const fetchAccount = async (current: YesCodeSession): Promise<Omit<QuotaSnapshot, 'fetchedAt'>> => {
+        const [profile, balance] = await Promise.all([
+          context.getJson(`${YESCODE_ORIGIN}/api/v1/auth/profile`, current.headers, context.signal),
+          // Optional endpoint: a plain 404 must not fail the whole query.
+          context.getJson(`${YESCODE_ORIGIN}/api/v1/user/balance`, current.headers, context.signal)
+            .catch((error: unknown) => {
+              if (error instanceof QuotaError && error.code === 'http') return undefined;
+              throw error;
+            }),
+        ]);
+        return parseYesCodeAccount(balance, profile);
+      };
+      if (!session || context.now() >= session.expiresAt) session = await login();
+      try {
+        return { ...await fetchAccount(session), fetchedAt: context.now() };
+      } catch (error) {
+        // Session died early (24h cookie or revocation): re-login once, then give up.
+        if (!(error instanceof QuotaError) || error.code !== 'auth') throw error;
+        session = await login();
+        return { ...await fetchAccount(session), fetchedAt: context.now() };
+      }
+    },
+  };
+}