@astrosheep/pi-quota 0.12.2 → 0.13.0

package/src/query/new-api.ts

@@ -1,10 +1,10 @@
 import { bearer } from './http.ts';
-import { numeric, object } from './parse.ts';
+import { numeric, object, percent } from './parse.ts';
 import { QuotaError } from './types.ts';
 import { safeBaseUrl } from './url.ts';
 import type { QuotaAdapter, QuotaSnapshot } from './types.ts';
 
-type Amounts = Pick<QuotaSnapshot, 'balance' | 'allowance' | 'spend'>;
+type Amounts = Omit<QuotaSnapshot, 'fetchedAt'>;
 
 export interface NewApiOptions {
   quotaPerUnit?: number;
@@ -43,9 +43,11 @@ export function parseNewApiTokenUsage(payload: unknown, options: NewApiOptions =
   if (data.object !== 'token_usage') return null;
   const used = numeric(data.total_used);
   if (used === null || !Number.isSafeInteger(used) || used < 0) throw new QuotaError('schema');
+  const spending = [{ id: 'key-lifetime', label: 'API key spend', currency,
+    amount: used / quotaPerUnit, period: 'lifetime' as const }];
   if (data.unlimited_quota === true) {
-    return { balance: { currency, remaining: 0, unlimited: true },
-      spend: { currency, lifetime: used / quotaPerUnit } };
+    return { balances: [], limits: [{ id: 'key-quota', label: 'Key quota',
+      remainingPercent: null, resetAt: null, unlimited: true }], spending };
   }
   const remaining = numeric(data.total_available);
   if (remaining === null || !Number.isSafeInteger(remaining)) throw new QuotaError('schema');
@@ -54,15 +56,17 @@ export function parseNewApiTokenUsage(payload: unknown, options: NewApiOptions =
 
   // New-api reports granted = key used + key remaining. Only draw a finite
   // allocation bar when the server actually supplies that total.
+  let limit: number | null = null;
   if (data.total_granted !== undefined) {
     const granted = numeric(data.total_granted);
     if (granted === null || !Number.isSafeInteger(granted) || granted < 0
       || !Number.isSafeInteger(used + remaining) || granted !== used + remaining) throw new QuotaError('schema');
-    if (granted > 0) return { allowance: { currency, limit: granted / quotaPerUnit,
-      used: used / quotaPerUnit, remaining: moneyLeft } };
+    limit = granted / quotaPerUnit;
   }
-  return { balance: { currency, remaining: moneyLeft },
-    spend: { currency, lifetime: used / quotaPerUnit } };
+  // Key quota is not owned account money. Missing total_granted stays unknown.
+  return { balances: [], limits: [{ id: 'key-quota', label: 'Key quota', resetAt: null,
+    remainingPercent: limit !== null && limit > 0 ? percent(moneyLeft / limit * 100) : null,
+    amounts: { unit: currency, limit, used: used / quotaPerUnit, remaining: moneyLeft } }], spending };
 }
 
 // GET /api/user/self (UserAuth): the console's own account quota, readable with
@@ -78,8 +82,9 @@ export function parseNewApiUserSelf(payload: unknown, options: NewApiOptions = {
   if (quota === null || usedQuota === null
     || !Number.isSafeInteger(quota) || !Number.isSafeInteger(usedQuota)
     || quota < 0 || usedQuota < 0) throw new QuotaError('schema');
-  return { balance: { currency, remaining: quota / quotaPerUnit },
-    spend: { currency, lifetime: usedQuota / quotaPerUnit } };
+  return { balances: [{ id: 'account', label: 'Balance', currency, remaining: quota / quotaPerUnit }],
+    limits: [], spending: [{ id: 'account-lifetime', label: 'Account spend', currency,
+      amount: usedQuota / quotaPerUnit, period: 'lifetime' }] };
 }
 
 // Legacy one-api billing pair, still the only option on older deployments.
@@ -96,10 +101,10 @@ export function parseNewApiBilling(subscription: unknown, usage: unknown, option
   const used = totalUsage / 100;
   // This endpoint reports account remaining + lifetime usage as its hard limit.
   // Top-ups change that total, so it is a wallet balance, not a fixed allowance.
-  if (limit >= 1e7) return { balance: { currency, remaining: 0, unlimited: true },
-    spend: { currency, lifetime: used } };
-  return { balance: { currency, remaining: limit - used },
-    spend: { currency, lifetime: used } };
+  const spending = [{ id: 'billing-lifetime', label: 'Reported spend', currency, amount: used, period: 'lifetime' as const }];
+  if (limit >= 1e7) return { balances: [], limits: [{ id: 'billing-quota', label: 'Quota',
+    remainingPercent: null, resetAt: null, unlimited: true }], spending };
+  return { balances: [{ id: 'account', label: 'Balance', currency, remaining: limit - used }], limits: [], spending };
 }
 
 export function createNewApiAdapter(provider: string, options: NewApiOptions = {}): QuotaAdapter {
@@ -129,7 +134,7 @@ export function createNewApiAdapter(provider: string, options: NewApiOptions = {
         if (dashboardUserId !== undefined) headers['New-Api-User'] = String(dashboardUserId);
         try {
           const payload = await context.getJson(`${root}/api/user/self`, headers, context.signal);
-          return { windows: [], ...parseNewApiUserSelf(payload, settings), fetchedAt: context.now() };
+          return { ...parseNewApiUserSelf(payload, settings), fetchedAt: context.now() };
         } catch (error) {
           if (!(error instanceof QuotaError)) throw error;
         }
@@ -145,7 +150,7 @@ export function createNewApiAdapter(provider: string, options: NewApiOptions = {
           context.getJson(`${root}/v1/dashboard/billing/usage?start_date=2020-01-01&end_date=2100-01-01`, headers, context.signal),
         ]);
         const billing = parseNewApiBilling(pair[0], pair[1], settings);
-        if (billing.balance?.unlimited !== true) return { windows: [], ...billing, fetchedAt: context.now() };
+        if (billing.balances.length > 0) return { ...billing, fetchedAt: context.now() };
         billingBalance = billing;
       } catch (error) {
         // 404: deployment has no billing pair. 401: try the key-native endpoint
@@ -157,15 +162,15 @@ export function createNewApiAdapter(provider: string, options: NewApiOptions = {
       try {
         const payload = await context.getJson(`${root}/api/usage/token/`, headers, context.signal);
         const parsed = parseNewApiTokenUsage(payload, settings);
-        if (parsed) return { windows: [], ...parsed, fetchedAt: context.now() };
+        if (parsed) return { ...parsed, fetchedAt: context.now() };
       } catch (error) {
         if (billingBalance && error instanceof QuotaError && error.code === 'http') {
-          return { windows: [], ...billingBalance, fetchedAt: context.now() };
+          return { ...billingBalance, fetchedAt: context.now() };
         }
         if (error instanceof QuotaError && error.code === 'auth') throw new QuotaError('account-access');
         throw error;
       }
-      if (billingBalance) return { windows: [], ...billingBalance, fetchedAt: context.now() };
+      if (billingBalance) return { ...billingBalance, fetchedAt: context.now() };
       throw new QuotaError('schema');
     },
   };

package/src/query/opencode-go.ts

@@ -1,7 +1,7 @@
 import { bearer, officialAuth } from './http.ts';
 import { numeric, object, percent, timestamp, windowLabel } from './parse.ts';
 import { QuotaError } from './types.ts';
-import type { QuotaAdapter, QuotaWindow } from './types.ts';
+import type { QuotaAdapter, UsageLimit } from './types.ts';
 
 // OpenCode Go (opencode.ai Zen Go plan) is a single official deployment, so the
 // window keys are fixed and undecorated: percent is already "used", and there is
@@ -12,9 +12,9 @@ const WINDOWS = [
   { key: 'monthly', duration: 2592000 }, // 30 days
 ] as const;
 
-export function parseOpenCodeGo(payload: unknown): QuotaWindow[] {
+export function parseOpenCodeGo(payload: unknown): UsageLimit[] {
   const usage = object(object(payload).usage);
-  const windows: QuotaWindow[] = [];
+  const windows: UsageLimit[] = [];
   for (const { key, duration } of WINDOWS) {
     if (usage[key] === undefined) continue;
     const detail = object(usage[key]);
@@ -41,7 +41,7 @@ export function createOpenCodeGoAdapter(provider: string): QuotaAdapter {
       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() };
+      return { balances: [], limits: parseOpenCodeGo(data), spending: [], fetchedAt: context.now() };
     },
   };
 }

package/src/query/registry.ts

@@ -1,6 +1,6 @@
 import { safeLabel } from './parse.ts';
 import { QuotaError } from './types.ts';
-import type { AccountBalance, QuotaAdapter, QuotaAllowance, QuotaSnapshot, SpendSummary } from './types.ts';
+import type { LimitAmounts, QuotaAdapter, QuotaSnapshot } from './types.ts';
 
 export class AdapterRegistry {
   private readonly adapters = new Map<string, QuotaAdapter>();
@@ -25,58 +25,83 @@ export class AdapterRegistry {
   }
 }
 
-// Validate even custom adapter output before it reaches the bar.
-export function validateSnapshot(snapshot: QuotaSnapshot): QuotaSnapshot {
-  if (!snapshot || !Number.isFinite(snapshot.fetchedAt) || !Array.isArray(snapshot.windows)
-    || (snapshot.windows.length === 0 && snapshot.balance === undefined
-      && snapshot.allowance === undefined)
-    || snapshot.windows.length > 64) throw new QuotaError('schema');
-  let balance: AccountBalance | undefined;
-  if (snapshot.balance !== undefined) {
-    const data = snapshot.balance;
-    if (!data || typeof data.currency !== 'string' || !/^[A-Z]{3}$/.test(data.currency)
-      || !Number.isFinite(data.remaining)
-      || (data.unlimited !== undefined && typeof data.unlimited !== 'boolean')) throw new QuotaError('schema');
-    balance = { currency: data.currency, remaining: data.remaining,
-      ...(data.unlimited === true ? { unlimited: true } : {}) };
-  }
-  const allowance = snapshot.allowance === undefined ? undefined : validateAllowance(snapshot.allowance);
-  let spend: SpendSummary | undefined;
-  if (snapshot.spend !== undefined) {
-    const data = snapshot.spend;
-    if (!data || typeof data.currency !== 'string' || !/^[A-Z]{3}$/.test(data.currency)
-      || (data.today === undefined && data.lifetime === undefined)
-      || (data.today !== undefined && (!Number.isFinite(data.today) || data.today < 0))
-      || (data.lifetime !== undefined && (!Number.isFinite(data.lifetime) || data.lifetime < 0))) {
+// Validate even custom/exec adapter output before it reaches a consumer.
+export function validateSnapshot(snapshot: unknown): QuotaSnapshot {
+  const data = record(snapshot);
+  if (!Number.isFinite(data.fetchedAt)
+    || ['windows', 'balance', 'allowance', 'spend'].some(key => key in data)) throw new QuotaError('schema');
+  const balances = entries(data.balances).map(entry => {
+    if (!isCurrency(entry.currency) || !Number.isFinite(entry.remaining)
+      || entry.unlimited !== undefined) throw new QuotaError('schema');
+    return { ...identity(entry), currency: entry.currency, remaining: entry.remaining as number };
+  });
+  const limits = entries(data.limits).map(entry => {
+    if ((entry.scope !== undefined && typeof entry.scope !== 'string')
+      || (entry.durationSeconds !== undefined && (!Number.isFinite(entry.durationSeconds) || (entry.durationSeconds as number) <= 0))
+      || (entry.remainingPercent !== null && (!Number.isFinite(entry.remainingPercent)
+        || (entry.remainingPercent as number) < 0 || (entry.remainingPercent as number) > 100))
+      || (entry.resetAt !== null && (!Number.isFinite(entry.resetAt) || (entry.resetAt as number) <= 0))
+      || (entry.unlimited !== undefined && entry.unlimited !== true)
+      || (entry.unlimited === true && (entry.amounts !== undefined || entry.remainingPercent !== null))) {
       throw new QuotaError('schema');
     }
-    spend = { currency: data.currency, ...(data.today !== undefined ? { today: data.today } : {}),
-      ...(data.lifetime !== undefined ? { lifetime: data.lifetime } : {}) };
+    return { ...identity(entry), remainingPercent: entry.remainingPercent as number | null,
+      resetAt: entry.resetAt as number | null,
+      ...(entry.scope !== undefined ? { scope: label(entry.scope) } : {}),
+      ...(entry.durationSeconds !== undefined ? { durationSeconds: entry.durationSeconds as number } : {}),
+      ...(entry.amounts !== undefined ? { amounts: validateAmounts(entry.amounts) } : {}),
+      ...(entry.unlimited === true ? { unlimited: true as const } : {}) };
+  });
+  const spending = entries(data.spending).map(entry => {
+    if (!isCurrency(entry.currency) || !Number.isFinite(entry.amount) || (entry.amount as number) < 0
+      || (entry.period !== 'today' && entry.period !== 'lifetime')) throw new QuotaError('schema');
+    return { ...identity(entry), currency: entry.currency, amount: entry.amount as number, period: entry.period as 'today' | 'lifetime' };
+  });
+  if (balances.length + limits.length + spending.length === 0) throw new QuotaError('schema');
+  return { balances, limits, spending, fetchedAt: data.fetchedAt as number };
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new QuotaError('schema');
+  return value as Record<string, unknown>;
+}
+
+function label(value: unknown): string {
+  if (typeof value !== 'string') throw new QuotaError('schema');
+  const clean = safeLabel(value).trim();
+  if (!clean) throw new QuotaError('schema');
+  return clean;
+}
+
+function identity(data: Record<string, unknown>): { id: string; label: string } {
+  // IDs are opaque and preserved, never derived from duration, scope or label.
+  if (typeof data.id !== 'string' || !data.id || data.id !== label(data.id) || data.id.length > 64) {
+    throw new QuotaError('schema');
   }
+  return { id: data.id, label: label(data.label) };
+}
+
+function entries(value: unknown): Record<string, unknown>[] {
+  if (!Array.isArray(value) || value.length > 64) throw new QuotaError('schema');
   const ids = new Set<string>();
-  const windows = snapshot.windows.map(window => {
-    if (!window || typeof window.id !== 'string' || ids.has(window.id)
-      || typeof window.label !== 'string'
-      || (window.scope !== undefined && typeof window.scope !== 'string')
-      || !Number.isFinite(window.durationSeconds) || window.durationSeconds <= 0
-      || (window.remainingPercent !== null && (!Number.isFinite(window.remainingPercent)
-        || window.remainingPercent < 0 || window.remainingPercent > 100))
-      || (window.resetAt !== null && (!Number.isFinite(window.resetAt) || window.resetAt <= 0))) {
-      throw new QuotaError('schema');
-    }
-    ids.add(window.id);
-    return { ...window, label: safeLabel(window.label),
-      ...(window.amounts !== undefined ? { amounts: validateAllowance(window.amounts) } : {}),
-      ...(window.scope !== undefined ? { scope: safeLabel(window.scope) } : {}) };
+  return value.map(item => {
+    const data = record(item);
+    const { id } = identity(data);
+    if (ids.has(id)) throw new QuotaError('schema');
+    ids.add(id);
+    return data;
   });
-  return { fetchedAt: snapshot.fetchedAt, windows, ...(balance ? { balance } : {}),
-    ...(allowance ? { allowance } : {}), ...(spend ? { spend } : {}) };
 }
 
-function validateAllowance(data: QuotaAllowance): QuotaAllowance {
-  if (!data || typeof data.currency !== 'string' || !/^[A-Z]{3}$/.test(data.currency)
-    || !Number.isFinite(data.limit) || data.limit <= 0
-    || !Number.isFinite(data.used) || data.used < 0
+function isCurrency(value: unknown): value is string {
+  return typeof value === 'string' && /^[A-Z]{3}$/.test(value);
+}
+
+function validateAmounts(value: unknown): LimitAmounts {
+  const data = record(value);
+  if ((data.limit !== null && (!Number.isFinite(data.limit) || (data.limit as number) < 0))
+    || !Number.isFinite(data.used) || (data.used as number) < 0
     || !Number.isFinite(data.remaining)) throw new QuotaError('schema');
-  return { currency: data.currency, limit: data.limit, used: data.used, remaining: data.remaining };
+  return { unit: label(data.unit), limit: data.limit as number | null,
+    used: data.used as number, remaining: data.remaining as number };
 }

package/src/query/sub2api.ts

@@ -2,7 +2,7 @@ import { bearer } from './http.ts';
 import { numeric, object, percent, timestamp } from './parse.ts';
 import { QuotaError } from './types.ts';
 import { safeBaseUrl } from './url.ts';
-import type { AccountBalance, QuotaAdapter, QuotaAllowance, QuotaSnapshot, QuotaWindow, ProviderAuth, SpendSummary } from './types.ts';
+import type { Balance, LimitAmounts, QuotaAdapter, QuotaSnapshot, UsageLimit, ProviderAuth, Spending } from './types.ts';
 
 export function sub2ApiUsageUrl(baseUrl: string | undefined): string {
   const url = safeBaseUrl(baseUrl);
@@ -23,23 +23,21 @@ function amount(value: unknown): number {
   return result;
 }
 
-function allowance(data: Record<string, unknown>, unit: string): QuotaAllowance {
+function allowance(data: Record<string, unknown>, unit: string): LimitAmounts {
   const limit = amount(data.limit);
   if (limit === 0) throw new QuotaError('schema');
   const used = amount(data.used);
   const remaining = amount(data.remaining);
-  return { currency: unit, limit, used, remaining };
+  return { unit, limit, used, remaining };
 }
 
-function spend(data: Record<string, unknown>, unit: string): SpendSummary | undefined {
-  const today = object(data.today);
-  const total = object(data.total);
-  const todayCost = numeric(today.actual_cost);
-  const lifetimeCost = numeric(total.actual_cost);
-  if (todayCost === null && lifetimeCost === null) return undefined;
-  if ((todayCost !== null && todayCost < 0) || (lifetimeCost !== null && lifetimeCost < 0)) throw new QuotaError('schema');
-  return { currency: unit, ...(todayCost !== null ? { today: todayCost } : {}),
-    ...(lifetimeCost !== null ? { lifetime: lifetimeCost } : {}) };
+function spend(data: Record<string, unknown>, currency: string): Spending[] {
+  return [['today', data.today], ['lifetime', data.total]].flatMap(([period, raw]) => {
+    const cost = object(raw).actual_cost;
+    if (cost === undefined) return [];
+    return [{ id: `key-${period}`, label: 'API key spend', currency, amount: amount(cost),
+      period: period as 'today' | 'lifetime' }];
+  });
 }
 
 function percentFromAmounts(remaining: number, limit: number): number {
@@ -48,16 +46,16 @@ function percentFromAmounts(remaining: number, limit: number): number {
 
 const RATE_WINDOWS: Record<string, number> = { '5h': 18000, '1d': 86400, '7d': 604800 };
 
-function rateWindow(data: Record<string, unknown>, unit: string): QuotaWindow {
+function rateWindow(data: Record<string, unknown>): UsageLimit {
   const label = data.window;
   if (typeof label !== 'string' || !Object.hasOwn(RATE_WINDOWS, label)) throw new QuotaError('schema');
-  const limits = allowance(data, unit);
+  const limits = allowance(data, 'USD');
   return { id: `rate-${label}`, label, durationSeconds: RATE_WINDOWS[label],
-    remainingPercent: percentFromAmounts(limits.remaining, limits.limit),
+    remainingPercent: percentFromAmounts(limits.remaining, limits.limit!),
     resetAt: timestamp(data.reset_at), amounts: limits };
 }
 
-function subscriptionWindows(data: Record<string, unknown>, unit: string): QuotaWindow[] {
+function subscriptionWindows(data: Record<string, unknown>): UsageLimit[] {
   const specs = [
     ['daily', '1d', 'daily_usage_usd', 'daily_limit_usd', 86400],
     ['weekly', '1w', 'weekly_usage_usd', 'weekly_limit_usd', 604800],
@@ -70,10 +68,9 @@ function subscriptionWindows(data: Record<string, unknown>, unit: string): Quota
     if (limit === 0) return []; // No cap for this period; no percentage can be computed.
     const used = numeric(data[usedKey]);
     if (used === null || used < 0) throw new QuotaError('schema');
-    const amounts: QuotaAllowance = { currency: unit, limit, used, remaining: Math.max(0, limit - used) };
-    const start = id === 'weekly' ? timestamp(data.weekly_window_start) : null;
+    const amounts: LimitAmounts = { unit: 'USD', limit, used, remaining: Math.max(0, limit - used) };
     return [{ id, label, durationSeconds, remainingPercent: percentFromAmounts(amounts.remaining, limit),
-      resetAt: start === null ? null : start + durationSeconds * 1000, amounts }];
+      resetAt: null, amounts }];
   });
 }
 
@@ -86,27 +83,29 @@ export function parseSub2ApiUsage(payload: unknown): Omit<QuotaSnapshot, 'fetche
   // Sub2API rate limits are always USD; a fixed quota carries its own unit.
   const unit = currency(body.unit ?? (body.mode === 'quota_limited'
     ? object(body.quota).unit ?? 'USD' : undefined));
-  const windows: QuotaWindow[] = [];
-  let balance: AccountBalance | undefined;
-  let finiteQuota: QuotaAllowance | undefined;
+  const limits: UsageLimit[] = [];
+  const balances: Balance[] = [];
   if (body.mode === 'quota_limited') {
-    const quota = body.quota === undefined ? undefined : allowance(object(body.quota), unit);
-    finiteQuota = quota;
+    if (body.quota !== undefined) {
+      const amounts = allowance(object(body.quota), unit);
+      limits.push({ id: 'key-quota', label: 'Key quota', resetAt: null,
+        remainingPercent: percentFromAmounts(amounts.remaining, amounts.limit!), amounts });
+    }
     const rates = body.rate_limits;
     if (rates !== undefined) {
       if (!Array.isArray(rates)) throw new QuotaError('schema');
-      rates.forEach(entry => windows.push(rateWindow(object(entry), unit)));
+      rates.forEach(entry => limits.push(rateWindow(object(entry))));
     }
   } else if (body.subscription !== undefined) {
-    windows.push(...subscriptionWindows(object(body.subscription), unit));
-  } else {
-    const remaining = amount(body.remaining ?? body.balance);
-    balance = { currency: unit, remaining };
+    limits.push(...subscriptionWindows(object(body.subscription)));
+  } else if (body.remaining !== undefined || body.balance !== undefined) {
+    const remaining = numeric(body.remaining ?? body.balance);
+    if (remaining === null) throw new QuotaError('schema');
+    balances.push({ id: 'wallet', label: 'Balance', currency: unit, remaining });
   }
-  const usage = spend(object(body.usage), unit);
-  if (windows.length === 0 && !balance && !finiteQuota) throw new QuotaError('schema');
-  return { windows, ...(balance ? { balance } : {}), ...(finiteQuota ? { allowance: finiteQuota } : {}),
-    ...(usage ? { spend: usage } : {}) };
+  const spending = spend(object(body.usage), unit);
+  if (limits.length + balances.length + spending.length === 0) throw new QuotaError('schema');
+  return { limits, balances, spending };
 }
 
 export function createSub2ApiAdapter(provider: string): QuotaAdapter {

package/src/query/types.ts

@@ -1,38 +1,41 @@
 // Query-layer contracts: no Pi, terminal, or rendering dependencies.
-export interface QuotaWindow {
+export interface Balance {
   id: string;
   label: string;
-  remainingPercent: number | null; // null is unknown, never silently 0 or 100
-  resetAt: number | null; // epoch milliseconds
-  durationSeconds: number;
-  scope?: string; // e.g. a model-specific Codex quota domain
-  amounts?: QuotaAllowance; // exact periodic amounts when exposed by the API
-}
-
-export interface AccountBalance {
   currency: string; // ISO-style currency code, e.g. USD
-  remaining: number; // may be negative (debt); not a periodic allowance
-  unlimited?: boolean; // provider granted no finite cap; ignore remaining
+  remaining: number; // finite; may be negative (debt); owned money, not a quota
 }
 
-export interface QuotaAllowance {
-  currency: string;
-  limit: number;
+export interface LimitAmounts {
+  unit: string; // currency code or a count unit, e.g. USD, CNY, tokens, requests
+  limit: number | null; // null when the API supplies amounts but no total cap
   used: number;
-  remaining: number;
+  remaining: number; // may be negative when overdrawn
 }
 
-export interface SpendSummary {
+export interface UsageLimit {
+  id: string;
+  label: string;
+  scope?: string; // e.g. a model-specific Codex quota domain
+  remainingPercent: number | null; // remaining, not used; null is unknown
+  resetAt: number | null; // epoch milliseconds; null is unknown/not supplied
+  durationSeconds?: number; // absence says nothing about whether it renews
+  amounts?: LimitAmounts; // independent of rounded/provider-specific percentages
+  unlimited?: true; // no finite cap; no amounts or fabricated percentage
+}
+
+export interface Spending {
+  id: string;
+  label: string;
   currency: string;
-  today?: number;
-  lifetime?: number;
+  amount: number;
+  period: 'today' | 'lifetime'; // today uses the provider's day, not an inferred timezone
 }
 
 export interface QuotaSnapshot {
-  windows: readonly QuotaWindow[];
-  balance?: AccountBalance;
-  allowance?: QuotaAllowance;
-  spend?: SpendSummary;
+  balances: Balance[];
+  limits: UsageLimit[];
+  spending: Spending[];
   fetchedAt: number;
 }
 

package/src/query/yescode.ts

@@ -1,7 +1,7 @@
 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';
+import type { PostJsonResult, QuotaAdapter, QuotaSnapshot, UsageLimit } from './types.ts';
 
 export const YESCODE_ORIGIN = 'https://co.yes.vg';
 
@@ -70,7 +70,7 @@ function nonNegative(value: unknown): number | undefined {
 }
 
 function limitWindow(id: string, label: string, durationSeconds: number,
-  limitRaw: unknown, usedRaw: unknown, resetAt: number | null): QuotaWindow[] {
+  limitRaw: unknown, usedRaw: unknown, resetAt: number | null): UsageLimit[] {
   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
@@ -79,17 +79,17 @@ function limitWindow(id: string, label: string, durationSeconds: number,
   }
   const remaining = Math.max(0, limit - used);
   return [{ id, label, durationSeconds, remainingPercent: percent(remaining / limit * 100), resetAt,
-    amounts: { currency: 'USD', limit, used, remaining } }];
+    amounts: { unit: '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 {
+function spendingLimitWindows(balanceData: Record<string, unknown>): UsageLimit[] | 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 windows = balanceData.spending_limits.flatMap((entry): UsageLimit[] => {
     const item = object(entry);
     const limit = nonNegative(item.limit);
     const spent = nonNegative(item.spent);
@@ -108,10 +108,10 @@ function spendingLimitWindows(balanceData: Record<string, unknown>): QuotaWindow
     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 } }];
+      amounts: { unit: 'USD', limit, used: spent, remaining: left } }];
   });
   // Footer/detail convention is ascending duration (5h → 1w → 30d).
-  return windows.sort((a, b) => a.durationSeconds - b.durationSeconds);
+  return windows.sort((a, b) => a.durationSeconds! - b.durationSeconds!);
 }
 
 export function parseYesCodeAccount(balancePayload: unknown, profilePayload: unknown): Omit<QuotaSnapshot, 'fetchedAt'> {
@@ -122,21 +122,20 @@ export function parseYesCodeAccount(balancePayload: unknown, profilePayload: unk
   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) ?? [
+  const limits = 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)),
+      timestamp(balanceData.weekly_resets_at ?? balanceData.weekly_reset_at)),
     ...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)),
+      timestamp(balanceData.monthly_resets_at ?? balanceData.monthly_reset_at)),
   ];
-  return { windows, balance: { currency: 'USD', remaining: (subscription ?? 0) + (paygo ?? 0) } };
+  return { limits, balances: [
+    ...(subscription !== undefined ? [{ id: 'subscription', label: 'Subscription', currency: 'USD', remaining: subscription }] : []),
+    ...(paygo !== undefined ? [{ id: 'paygo', label: 'Pay-as-you-go', currency: 'USD', remaining: paygo }] : []),
+  ], spending: [] };
 }
 
 export function createYesCodeAdapter(provider: string, options: YesCodeOptions): QuotaAdapter {