@astrosheep/pi-quota 0.12.1 → 0.13.0

package/README.md

@@ -12,13 +12,15 @@ Reload Pi after installing or changing settings. Use `/usage` for a persistent,
 
 | Kind | Footer | `/usage` |
 |---|---|---|
-| Renewable window | `5h [▆] 72% ↺ 2h15m` | Horizontal bar, remaining percentage, reset, exact amounts if available |
-| Wallet | `Bal $12.34` | Balance; optional Today/Lifetime spend |
-| Fixed quota | `Quota [▇] $85.00` | Remaining bar plus used and limit |
+| Usage limit with a known period | `5h [▆] 72% ↺ 2h15m` | Horizontal bar, remaining percentage, reset, exact amounts if available |
+| Wallet | `Bal $12.34` | Each finite balance, separately from limits and spend |
+| Amount-based limit without a supplied period | `Key quota [▇] $85.00` | Remaining percentage plus exact remaining/used/cap amounts |
+| Unlimited limit | `Key quota ∞` | Unlimited, without fake money or a percentage |
+| Spending | Not shown | Today expenses; Lifetime is retained in data, not displayed |
 
 A percentage always means **remaining**, not used. Unknown is `[?] ?`; an expired reset is `↺ due` with the stale percentage hidden until the next successful query. A wallet balance never becomes a percentage. Historical spend is not a quota.
 
-The footer shows at most two windows — set `quotaUsage.footerWindows` to a positive integer or `"all"` to show more — and `+N` for additional ones, for the current provider only. `/usage` queries all configured supported providers and shows successful results with all windows, grouped by provider; it does not open a modal or send messages to the model. Snapshots remain frozen at capture time. Query failures replace stale values in the footer and appear in `/usage --all`.
+The footer shows every balance, then limits in adapter order, capped at two by default — set `quotaUsage.footerWindows` to a positive integer or `"all"` to show more — followed by `+N` for limits it did not show, for the current provider only. Shared limits are preferred over scoped ones, so a scoped limit can be counted in `+N`. `/usage` queries all configured supported providers and shows every balance, limit and Today spending entry, grouped by provider; it does not open a modal or send messages to the model. Snapshots remain frozen at capture time. Query failures replace stale values in the footer and appear in `/usage --all`.
 
 ## Configure providers
 
@@ -45,10 +47,10 @@ Use the **exact Pi provider ID**. Built-in providers and explicitly bound provid
 | Adapter | Endpoint | Result |
 |---|---|---|
 | `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 |
+| `new-api` | Account PAT `/api/user/self`, falling back to key-native billing/token endpoints | Account balance + lifetime spend; key limits (finite or unlimited), with no invented renewal |
+| `deepseek` | Official `/user/balance` | All reported currency balances; 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 |
+| `yescode` | `co.yes.vg` login → session → `/api/v1/auth/profile` + `/api/v1/user/balance` | Separate subscription/pay-as-you-go balances plus scoped subscription limits |
 | `exec` | Runs `command` as argv (no shell), parses stdout as a `QuotaSnapshot` JSON | Whatever the command reports; `fetchedAt` is stamped by the adapter, never by the command |
 | `alias` | No endpoint — delegates to the `of` binding (built-in or explicit) | Shares the target account's quota; one folded row in `/usage` |
 
@@ -56,11 +58,11 @@ Bind `opencode-go` to a second OpenCode Go account: register it as its own Pi pr
 
 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 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 known percentage only when `total_granted` is present and consistent with used plus remaining; otherwise its limit retains exact used/remaining with `amounts.limit: null` and an unknown percentage. It never becomes a wallet. `unlimited_quota` and legacy billing's unlimited sentinel become unlimited **limits**, not infinite balances. 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.
+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. Subscription and pay-as-you-go balances remain separate; daily/weekly limits appear only when the account actually has those caps. Only an explicitly reported next reset is preserved; `last_*_reset` does not establish a future schedule.
 
-Exec runs the configured argv without a shell and parses stdout as a `QuotaSnapshot` JSON object: `windows`, optional `balance`, `allowance` and `spend` — the same schema every adapter produces, enforced by the controller. `fetchedAt` is stamped by the adapter; a value from the command is ignored. The controller bounds every query (10s default) and kills the child on timeout; non-zero exits, unreadable JSON and output over 256KB become errors, and command output is never logged. The child inherits Pi's environment, so keep secrets in env vars, not in `quotaUsage`.
+Exec runs the configured argv without a shell and parses stdout as a JSON object with required `balances`, `limits` and `spending` arrays — the same schema every adapter produces, enforced by the controller. This is a **breaking query/exec contract migration**: legacy `windows`, `balance`, `allowance` and `spend` fields are rejected, not converted. `fetchedAt` is stamped by the adapter; a value from the command is ignored. The controller bounds every query (10s default) and kills the child on timeout; non-zero exits, unreadable JSON and output over 256KB become errors, and command output is never logged. The child inherits Pi's environment, so keep secrets in env vars, not in `quotaUsage`.
 
 Alias binds a second provider ID to the same account: `"of"` names the real binding, which may be a built-in or an explicit adapter. The alias never queries on its own — a session on the alias shows the target's quota in the footer, queried under the target's identity and credentials, and `/usage` folds the alias into the target's single row with the session pin (and ★) following the fold. Aliases are one hop: `of` must not itself be an alias, and an alias whose target is not configured fails visibly instead of vanishing.
 
@@ -77,9 +79,72 @@ Pi model/auth → adapter → QuotaSnapshot → controller → footer / /usage /
 - `src/bar/`: pure compact rendering and persistent multi-provider chat card.
 - `src/extension.ts` and `src/index.ts`: Pi lifecycle and auth bridge.
 
-`QuotaSnapshot` separates `balance` (wallet), `allowance` (finite key quota), `windows` (renewable limits), and optional `spend` (Today/Lifetime actual charge). This prevents unrelated amounts from sharing an ambiguous `Used` label. Custom adapters can be passed to `createQuotaExtension({ adapters: [...] })`; see `examples/custom-provider.ts`. Provider aliases are never inferred.
+`QuotaSnapshot` preserves three independent concepts: `balances` (owned money), `limits` (periodic and non-periodic allowances), and `spending` (reported expenses, not necessarily wallet debit or limit consumption). Pi providers only select/bind adapters; the model adds no inferred owner/account graph. Custom adapters can be passed to `createQuotaExtension({ adapters: [...] })`; see `examples/custom-provider.ts`. Provider aliases are never inferred.
 
-The extension publishes structured state on `quota-bar:state:v1`. Use `createQuotaExtension({ footer: false })` to consume it without this extension's footer. Normal queries are throttled, cancellable, timeout-bounded and backed off after errors. `/usage` forces a fresh query for every configured supported provider, then omits failed results from its default view. Switching provider discards old footer values immediately.
+The extension publishes structured state on `quota-bar:state:v2` and saves usage cards under `quota-bar:usage:v2`; old contract events/cards are not migrated. Use `createQuotaExtension({ footer: false })` to consume it without this extension's footer. Normal queries are throttled, cancellable, timeout-bounded and backed off after errors. `/usage` forces a fresh query for every configured supported provider, then omits failed results from its default view. Switching provider discards old footer values immediately.
+
+## Snapshot schema
+
+All types below are named exports of `@astrosheep/pi-quota/query`:
+
+```ts
+interface Balance {
+  id: string;
+  label: string;
+  currency: string;
+  remaining: number;
+}
+interface LimitAmounts {
+  unit: string;
+  limit: number | null;
+  used: number;
+  remaining: number;
+}
+interface UsageLimit {
+  id: string;
+  label: string;
+  scope?: string;
+  remainingPercent: number | null;
+  resetAt: number | null;
+  durationSeconds?: number;
+  amounts?: LimitAmounts;
+  unlimited?: true;
+}
+interface Spending {
+  id: string;
+  label: string;
+  currency: string;
+  amount: number;
+  period: 'today' | 'lifetime';
+}
+interface QuotaSnapshot {
+  balances: Balance[];
+  limits: UsageLimit[];
+  spending: Spending[];
+  fetchedAt: number;
+}
+```
+
+- All three arrays are required, with at most 64 entries each. Spend-only snapshots are valid; all-empty snapshots are not.
+- IDs are nonblank, control-free strings of at most 64 characters, unique **within each category**. They are opaque and preserved exactly, never derived from duration: two `5h` limits with different IDs remain distinct. Labels/scopes/units are sanitized for terminal safety, trimmed and bounded to 64 characters; blank values are rejected.
+- Currency is a three-letter uppercase code. Balances are finite, including zero and negative debt. They cannot be unlimited.
+- Percentages are finite values in `[0, 100]`, always **remaining**; `null` means unknown. Exact amounts and provider percentages need not agree after rounding or provider-specific accounting. `limit` is nonnegative or `null` (cap not reported); `used` is nonnegative; `remaining` is finite and may be negative. Amount units can be currencies or counts such as `tokens`/`requests`; counts are not formatted as money.
+- Unlimited limits use `unlimited: true`, `remainingPercent: null`, and no `amounts`. Unknown cap (`amounts.limit: null`) does **not** mean unlimited.
+- `fetchedAt` and `resetAt` are epoch milliseconds; `resetAt` is positive or `null`. A supplied duration must be positive. Missing duration/reset is unknown, not proof of no renewal. No fixed/rolling classification or future reset schedule is inferred.
+- Spending amounts are finite and nonnegative. `today` means the **provider-defined day**, with no inferred timezone. Both periods are retained in snapshots, but the footer omits spending and `/usage` displays only Today.
+
+For example, an exec command can emit this (no `fetchedAt` required):
+
+```json
+{
+  "balances": [{ "id": "wallet", "label": "Balance", "currency": "USD", "remaining": 12.34 }],
+  "limits": [{
+    "id": "requests", "label": "Requests", "remainingPercent": 80, "resetAt": null,
+    "amounts": { "unit": "requests", "limit": 100, "used": 20, "remaining": 80 }
+  }],
+  "spending": [{ "id": "today", "label": "Reported spend", "currency": "USD", "amount": 2.5, "period": "today" }]
+}
+```
 
 ## Standalone query layer
 
@@ -111,5 +176,6 @@ Requires Node ≥22.18 and a compatible Pi installation.
 npm install --ignore-scripts
 npm test
 npm run typecheck
+npm run build
 npm run demo
 ```

package/dist/query/codex.d.ts

@@ -1,4 +1,4 @@
-import type { QuotaAdapter, QuotaWindow } from './types.js';
+import type { QuotaAdapter, UsageLimit } from './types.js';
 export declare function codexAccountId(token: string): string | undefined;
-export declare function parseCodex(payload: unknown, now: number): QuotaWindow[];
+export declare function parseCodex(payload: unknown, now: number): UsageLimit[];
 export declare const codexAdapter: QuotaAdapter;

package/dist/query/codex.js

@@ -63,6 +63,6 @@ export const codexAdapter = {
             Origin: 'https://chatgpt.com', Referer: 'https://chatgpt.com/',
         }, context.signal);
         const now = context.now();
-        return { windows: parseCodex(data, now), fetchedAt: now };
+        return { balances: [], limits: parseCodex(data, now), spending: [], fetchedAt: now };
     },
 };

package/dist/query/deepseek.d.ts

@@ -1,4 +1,4 @@
-import type { AccountBalance, QuotaAdapter } from './types.js';
+import type { Balance, QuotaAdapter } from './types.js';
 export declare const DEEPSEEK_ORIGIN = "https://api.deepseek.com";
-export declare function parseDeepSeekBalance(payload: unknown): AccountBalance;
+export declare function parseDeepSeekBalance(payload: unknown): Balance[];
 export declare function createDeepSeekAdapter(provider: string): QuotaAdapter;

package/dist/query/deepseek.js

@@ -9,16 +9,15 @@ export function parseDeepSeekBalance(payload) {
     const body = object(payload);
     if (!Array.isArray(body.balance_infos) || body.balance_infos.length === 0)
         throw new QuotaError('schema');
-    for (const entry of body.balance_infos) {
+    return body.balance_infos.map(entry => {
         const info = object(entry);
         const remaining = numeric(info.total_balance);
         if (typeof info.currency !== 'string' || !/^[A-Z]{3}$/.test(info.currency)
-            || remaining === null || remaining < 0)
-            continue;
-        // The endpoint exposes no usage total; only return the actual balance.
-        return { currency: info.currency, remaining };
-    }
-    throw new QuotaError('schema');
+            || remaining === null)
+            throw new QuotaError('schema');
+        // Preserve each currency; the endpoint exposes no usage total.
+        return { id: info.currency, label: 'Balance', currency: info.currency, remaining };
+    });
 }
 export function createDeepSeekAdapter(provider) {
     return {
@@ -26,7 +25,7 @@ export function createDeepSeekAdapter(provider) {
         async query(context) {
             const auth = await officialAuth(context, DEEPSEEK_ORIGIN);
             const payload = await context.getJson(`${DEEPSEEK_ORIGIN}/user/balance`, { Authorization: `Bearer ${bearer(auth)}` }, context.signal);
-            return { windows: [], balance: parseDeepSeekBalance(payload), fetchedAt: context.now() };
+            return { balances: parseDeepSeekBalance(payload), limits: [], spending: [], fetchedAt: context.now() };
         },
     };
 }

package/dist/query/kimi.d.ts

@@ -1,3 +1,3 @@
-import type { QuotaAdapter, QuotaWindow } from './types.js';
-export declare function parseKimi(payload: unknown): QuotaWindow[];
+import type { QuotaAdapter, UsageLimit } from './types.js';
+export declare function parseKimi(payload: unknown): UsageLimit[];
 export declare const kimiAdapter: QuotaAdapter;

package/dist/query/kimi.js

@@ -47,6 +47,6 @@ export const kimiAdapter = {
         const data = await context.getJson('https://api.kimi.com/coding/v1/usages', {
             Authorization: `Bearer ${bearer(auth)}`,
         }, context.signal);
-        return { windows: parseKimi(data), fetchedAt: context.now() };
+        return { balances: [], limits: parseKimi(data), spending: [], fetchedAt: context.now() };
     },
 };

package/dist/query/new-api.d.ts

@@ -1,5 +1,5 @@
 import type { QuotaAdapter, QuotaSnapshot } from './types.js';
-type Amounts = Pick<QuotaSnapshot, 'balance' | 'allowance' | 'spend'>;
+type Amounts = Omit<QuotaSnapshot, 'fetchedAt'>;
 export interface NewApiOptions {
     quotaPerUnit?: number;
     currency?: string;

package/dist/query/new-api.js

@@ -1,5 +1,5 @@
 import { bearer } from "./http.js";
-import { numeric, object } from "./parse.js";
+import { numeric, object, percent } from "./parse.js";
 import { QuotaError } from "./types.js";
 import { safeBaseUrl } from "./url.js";
 export function validateNewApiOptions(options) {
@@ -32,9 +32,11 @@ export function parseNewApiTokenUsage(payload, options = {}) {
     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' }];
     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))
@@ -44,17 +46,18 @@ export function parseNewApiTokenUsage(payload, options = {}) {
         throw new QuotaError('schema');
     // New-api reports granted = key used + key remaining. Only draw a finite
     // allocation bar when the server actually supplies that total.
+    let limit = 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
 // a dashboard access token (PAT), which sk- keys are not. Old forks also demand
@@ -71,8 +74,9 @@ export function parseNewApiUserSelf(payload, options = {}) {
         || !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.
 // total_usage is in cents (divide by 100, per one-api issue #1785); most
@@ -89,11 +93,11 @@ export function parseNewApiBilling(subscription, usage, options = {}) {
     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.
+    const spending = [{ id: 'billing-lifetime', label: 'Reported spend', currency, amount: used, period: 'lifetime' }];
     if (limit >= 1e7)
-        return { balance: { currency, remaining: 0, unlimited: true },
-            spend: { currency, lifetime: used } };
-    return { balance: { currency, remaining: limit - used },
-        spend: { currency, lifetime: used } };
+        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, options = {}) {
     const settings = validateNewApiOptions(options);
@@ -128,7 +132,7 @@ export function createNewApiAdapter(provider, options = {}) {
                     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))
@@ -146,8 +150,8 @@ export function createNewApiAdapter(provider, options = {}) {
                     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) {
@@ -162,18 +166,18 @@ export function createNewApiAdapter(provider, options = {}) {
                 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() };
+                    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() };
+                return { ...billingBalance, fetchedAt: context.now() };
             throw new QuotaError('schema');
         },
     };

package/dist/query/opencode-go.d.ts

@@ -1,4 +1,4 @@
-import type { QuotaAdapter, QuotaWindow } from './types.js';
-export declare function parseOpenCodeGo(payload: unknown): QuotaWindow[];
+import type { QuotaAdapter, UsageLimit } from './types.js';
+export declare function parseOpenCodeGo(payload: unknown): UsageLimit[];
 export declare function createOpenCodeGoAdapter(provider: string): QuotaAdapter;
 export declare const openCodeGoAdapter: QuotaAdapter;

package/dist/query/opencode-go.js

@@ -39,7 +39,7 @@ export function createOpenCodeGoAdapter(provider) {
             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/dist/query/registry.d.ts

@@ -6,4 +6,4 @@ export declare class AdapterRegistry {
     get(provider: string | undefined): QuotaAdapter | undefined;
     list(): readonly QuotaAdapter[];
 }
-export declare function validateSnapshot(snapshot: QuotaSnapshot): QuotaSnapshot;
+export declare function validateSnapshot(snapshot: unknown): QuotaSnapshot;

package/dist/query/registry.js

@@ -19,60 +19,87 @@ export class AdapterRegistry {
         return [...this.adapters.values()];
     }
 }
-// Validate even custom adapter output before it reaches the bar.
+// Validate even custom/exec adapter output before it reaches a consumer.
 export function validateSnapshot(snapshot) {
-    if (!snapshot || !Number.isFinite(snapshot.fetchedAt) || !Array.isArray(snapshot.windows)
-        || (snapshot.windows.length === 0 && snapshot.balance === undefined
-            && snapshot.allowance === undefined)
-        || snapshot.windows.length > 64)
+    const data = record(snapshot);
+    if (!Number.isFinite(data.fetchedAt)
+        || ['windows', 'balance', 'allowance', 'spend'].some(key => key in data))
         throw new QuotaError('schema');
-    let balance;
-    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'))
+    const balances = entries(data.balances).map(entry => {
+        if (!isCurrency(entry.currency) || !Number.isFinite(entry.remaining)
+            || entry.unlimited !== undefined)
             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;
-    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))) {
+        return { ...identity(entry), currency: entry.currency, remaining: entry.remaining };
+    });
+    const limits = entries(data.limits).map(entry => {
+        if ((entry.scope !== undefined && typeof entry.scope !== 'string')
+            || (entry.durationSeconds !== undefined && (!Number.isFinite(entry.durationSeconds) || entry.durationSeconds <= 0))
+            || (entry.remainingPercent !== null && (!Number.isFinite(entry.remainingPercent)
+                || entry.remainingPercent < 0 || entry.remainingPercent > 100))
+            || (entry.resetAt !== null && (!Number.isFinite(entry.resetAt) || entry.resetAt <= 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,
+            resetAt: entry.resetAt,
+            ...(entry.scope !== undefined ? { scope: label(entry.scope) } : {}),
+            ...(entry.durationSeconds !== undefined ? { durationSeconds: entry.durationSeconds } : {}),
+            ...(entry.amounts !== undefined ? { amounts: validateAmounts(entry.amounts) } : {}),
+            ...(entry.unlimited === true ? { unlimited: true } : {}) };
+    });
+    const spending = entries(data.spending).map(entry => {
+        if (!isCurrency(entry.currency) || !Number.isFinite(entry.amount) || entry.amount < 0
+            || (entry.period !== 'today' && entry.period !== 'lifetime'))
+            throw new QuotaError('schema');
+        return { ...identity(entry), currency: entry.currency, amount: entry.amount, period: entry.period };
+    });
+    if (balances.length + limits.length + spending.length === 0)
+        throw new QuotaError('schema');
+    return { balances, limits, spending, fetchedAt: data.fetchedAt };
+}
+function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new QuotaError('schema');
+    return value;
+}
+function label(value) {
+    if (typeof value !== 'string')
+        throw new QuotaError('schema');
+    const clean = safeLabel(value).trim();
+    if (!clean)
+        throw new QuotaError('schema');
+    return clean;
+}
+function identity(data) {
+    // 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) {
+    if (!Array.isArray(value) || value.length > 64)
+        throw new QuotaError('schema');
     const ids = new Set();
-    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))) {
+    return value.map(item => {
+        const data = record(item);
+        const { id } = identity(data);
+        if (ids.has(id))
             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) } : {}) };
+        ids.add(id);
+        return data;
     });
-    return { fetchedAt: snapshot.fetchedAt, windows, ...(balance ? { balance } : {}),
-        ...(allowance ? { allowance } : {}), ...(spend ? { spend } : {}) };
 }
-function validateAllowance(data) {
-    if (!data || typeof data.currency !== 'string' || !/^[A-Z]{3}$/.test(data.currency)
-        || !Number.isFinite(data.limit) || data.limit <= 0
+function isCurrency(value) {
+    return typeof value === 'string' && /^[A-Z]{3}$/.test(value);
+}
+function validateAmounts(value) {
+    const data = record(value);
+    if ((data.limit !== null && (!Number.isFinite(data.limit) || data.limit < 0))
         || !Number.isFinite(data.used) || data.used < 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,
+        used: data.used, remaining: data.remaining };
 }

package/dist/query/sub2api.js

@@ -4,7 +4,9 @@ import { QuotaError } from "./types.js";
 import { safeBaseUrl } from "./url.js";
 export function sub2ApiUsageUrl(baseUrl) {
     const url = safeBaseUrl(baseUrl);
-    url.pathname = `${url.pathname.replace(/\/+$/, '')}/usage`;
+    // Anthropic clients use the host root; OpenAI clients include /v1.
+    const prefix = url.pathname.replace(/\/+$/, '') || '/v1';
+    url.pathname = `${prefix}/usage`;
     return url.toString();
 }
 function currency(value) {
@@ -24,34 +26,31 @@ function allowance(data, unit) {
         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, unit) {
-    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, currency) {
+    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 }];
+    });
 }
 function percentFromAmounts(remaining, limit) {
     return percent(remaining / limit * 100);
 }
 const RATE_WINDOWS = { '5h': 18000, '1d': 86400, '7d': 604800 };
-function rateWindow(data, unit) {
+function rateWindow(data) {
     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),
         resetAt: timestamp(data.reset_at), amounts: limits };
 }
-function subscriptionWindows(data, unit) {
+function subscriptionWindows(data) {
     const specs = [
         ['daily', '1d', 'daily_usage_usd', 'daily_limit_usd', 86400],
         ['weekly', '1w', 'weekly_usage_usd', 'weekly_limit_usd', 604800],
@@ -68,10 +67,9 @@ function subscriptionWindows(data, unit) {
         const used = numeric(data[usedKey]);
         if (used === null || used < 0)
             throw new QuotaError('schema');
-        const amounts = { currency: unit, limit, used, remaining: Math.max(0, limit - used) };
-        const start = id === 'weekly' ? timestamp(data.weekly_window_start) : null;
+        const amounts = { 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 }];
     });
 }
 export function parseSub2ApiUsage(payload) {
@@ -83,31 +81,34 @@ export function parseSub2ApiUsage(payload) {
     // 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 = [];
-    let balance;
-    let finiteQuota;
+    const limits = [];
+    const balances = [];
     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));
+        limits.push(...subscriptionWindows(object(body.subscription)));
     }
-    else {
-        const remaining = amount(body.remaining ?? body.balance);
-        balance = { currency: unit, remaining };
+    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)
+    const spending = spend(object(body.usage), unit);
+    if (limits.length + balances.length + spending.length === 0)
         throw new QuotaError('schema');
-    return { windows, ...(balance ? { balance } : {}), ...(finiteQuota ? { allowance: finiteQuota } : {}),
-        ...(usage ? { spend: usage } : {}) };
+    return { limits, balances, spending };
 }
 export function createSub2ApiAdapter(provider) {
     return {