@astrosheep/pi-quota 0.5.0

package/src/query/registry.ts

@@ -0,0 +1,78 @@
+import { safeLabel } from './parse.ts';
+import { QuotaError } from './types.ts';
+import type { AccountBalance, QuotaAdapter, QuotaAllowance, QuotaSnapshot, SpendSummary } from './types.ts';
+
+export class AdapterRegistry {
+  private readonly adapters = new Map<string, QuotaAdapter>();
+
+  constructor(adapters: readonly QuotaAdapter[] = []) {
+    for (const adapter of adapters) this.register(adapter);
+  }
+
+  register(adapter: QuotaAdapter): void {
+    if (!adapter.provider || !adapter.label || this.adapters.has(adapter.provider)) {
+      throw new Error('Quota adapter must have a unique provider ID and a label');
+    }
+    this.adapters.set(adapter.provider, { ...adapter, label: safeLabel(adapter.label) });
+  }
+
+  get(provider: string | undefined): QuotaAdapter | undefined {
+    return provider ? this.adapters.get(provider) : undefined;
+  }
+}
+
+// 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))) {
+      throw new QuotaError('schema');
+    }
+    spend = { currency: data.currency, ...(data.today !== undefined ? { today: data.today } : {}),
+      ...(data.lifetime !== undefined ? { lifetime: data.lifetime } : {}) };
+  }
+  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 { 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
+    || !Number.isFinite(data.remaining)) throw new QuotaError('schema');
+  return { currency: data.currency, limit: data.limit, used: data.used, remaining: data.remaining };
+}

package/src/query/sub2api.ts

@@ -0,0 +1,123 @@
+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';
+
+export function sub2ApiUsageUrl(baseUrl: string | undefined): string {
+  const url = safeBaseUrl(baseUrl);
+  url.pathname = `${url.pathname.replace(/\/+$/, '')}/usage`;
+  return url.toString();
+}
+
+function currency(value: unknown): string {
+  if (typeof value !== 'string' || !/^[A-Z]{3}$/.test(value)) throw new QuotaError('schema');
+  return value;
+}
+
+function amount(value: unknown): number {
+  const result = numeric(value);
+  if (result === null || result < 0) throw new QuotaError('schema');
+  return result;
+}
+
+function allowance(data: Record<string, unknown>, unit: string): QuotaAllowance {
+  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 };
+}
+
+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 percentFromAmounts(remaining: number, limit: number): number {
+  return percent(remaining / limit * 100);
+}
+
+const RATE_WINDOWS: Record<string, number> = { '5h': 18000, '1d': 86400, '7d': 604800 };
+
+function rateWindow(data: Record<string, unknown>, unit: string): QuotaWindow {
+  const label = data.window;
+  if (typeof label !== 'string' || !Object.hasOwn(RATE_WINDOWS, label)) throw new QuotaError('schema');
+  const limits = allowance(data, unit);
+  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: Record<string, unknown>, unit: string): QuotaWindow[] {
+  const specs = [
+    ['daily', '1d', 'daily_usage_usd', 'daily_limit_usd', 86400],
+    ['weekly', '1w', 'weekly_usage_usd', 'weekly_limit_usd', 604800],
+    ['monthly', '30d', 'monthly_usage_usd', 'monthly_limit_usd', 2592000],
+  ] as const;
+  return specs.flatMap(([id, label, usedKey, limitKey, durationSeconds]) => {
+    if (data[limitKey] == null) return []; // Upstream sends null for an unconfigured cap.
+    const limit = numeric(data[limitKey]);
+    if (limit === null || limit < 0) throw new QuotaError('schema');
+    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;
+    return [{ id, label, durationSeconds, remainingPercent: percentFromAmounts(amounts.remaining, limit),
+      resetAt: start === null ? null : start + durationSeconds * 1000, amounts }];
+  });
+}
+
+export function parseSub2ApiUsage(payload: unknown): Omit<QuotaSnapshot, 'fetchedAt'> {
+  const body = object(payload);
+  if (body.isValid !== true || (body.mode !== 'quota_limited' && body.mode !== 'unrestricted')) {
+    throw new QuotaError('schema');
+  }
+  // Upstream omits `unit` when a key has rate limits but no total quota.
+  // 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;
+  if (body.mode === 'quota_limited') {
+    const quota = body.quota === undefined ? undefined : allowance(object(body.quota), unit);
+    finiteQuota = quota;
+    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)));
+    }
+  } else if (body.subscription !== undefined) {
+    windows.push(...subscriptionWindows(object(body.subscription), unit));
+  } else {
+    const remaining = amount(body.remaining ?? body.balance);
+    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 } : {}) };
+}
+
+export function createSub2ApiAdapter(provider: string): QuotaAdapter {
+  return {
+    provider, label: provider,
+    async query(context) {
+      let auth: ProviderAuth | undefined;
+      try { auth = await context.getAuth(context.provider); } catch { throw new QuotaError('auth'); }
+      context.signal.throwIfAborted();
+      if (!auth) throw new QuotaError('auth');
+      const payload = await context.getJson(sub2ApiUsageUrl(auth.baseUrl),
+        { Authorization: `Bearer ${bearer(auth)}` }, context.signal);
+      return { ...parseSub2ApiUsage(payload), fetchedAt: context.now() };
+    },
+  };
+}

package/src/query/types.ts

@@ -0,0 +1,76 @@
+// Query-layer contracts: no Pi, terminal, or rendering dependencies.
+export interface QuotaWindow {
+  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
+}
+
+export interface QuotaAllowance {
+  currency: string;
+  limit: number;
+  used: number;
+  remaining: number;
+}
+
+export interface SpendSummary {
+  currency: string;
+  today?: number;
+  lifetime?: number;
+}
+
+export interface QuotaSnapshot {
+  windows: readonly QuotaWindow[];
+  balance?: AccountBalance;
+  allowance?: QuotaAllowance;
+  spend?: SpendSummary;
+  fetchedAt: number;
+}
+
+export interface ProviderAuth {
+  apiKey?: string;
+  headers?: Record<string, string | undefined>;
+  baseUrl?: 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>;
+}
+
+export interface QuotaAdapter {
+  provider: string; // exact Pi provider ID; aliases must be explicitly registered
+  label: string;
+  query(context: QueryContext): Promise<QuotaSnapshot>;
+}
+
+export type QuotaErrorCode = 'auth' | 'unsupported-auth' | 'account-access' | 'network' | 'timeout' | 'rate-limit' | 'http' | 'schema';
+
+export class QuotaError extends Error {
+  readonly code: QuotaErrorCode;
+  readonly retryAfterMs?: number;
+
+  constructor(code: QuotaErrorCode, retryAfterMs?: number) {
+    super(code); // Never include response bodies, request headers, or raw exceptions.
+    this.code = code;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export type QuotaState =
+  | { kind: 'hidden' }
+  | { kind: 'loading'; provider: string; label: string }
+  | { kind: 'ready'; provider: string; label: string; snapshot: QuotaSnapshot }
+  | { kind: 'error'; provider: string; label: string; code: QuotaErrorCode };

package/src/query/url.ts

@@ -0,0 +1,13 @@
+import { QuotaError } from './types.ts';
+
+// Validate a model endpoint before deriving any authenticated quota URL.
+// Never accept redirects (see http.ts) or move credentials to another origin.
+export function safeBaseUrl(baseUrl: string | undefined): URL {
+  if (!baseUrl) throw new QuotaError('unsupported-auth');
+  let url: URL;
+  try { url = new URL(baseUrl); } catch { throw new QuotaError('unsupported-auth'); }
+  const loopback = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+  if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback))
+    || url.username || url.password || url.search || url.hash) throw new QuotaError('unsupported-auth');
+  return url;
+}