@latentminds/pi-quotas 0.1.0

package/src/providers/parse.test.ts

@@ -0,0 +1,256 @@
+import { describe, expect, it } from "vitest";
+import { parseAnthropicUsage } from "./providers.js";
+import { parseCodexUsage } from "./providers.js";
+import { parseGitHubCopilotUsage } from "./providers.js";
+
+describe("parseAnthropicUsage", () => {
+  it("maps oauth usage response into quota windows", () => {
+    const windows = parseAnthropicUsage({
+      five_hour: {
+        utilization: 23.4,
+        resets_at: "2026-04-22T18:30:00Z",
+      },
+      seven_day: {
+        utilization: 14.1,
+        resets_at: "2026-04-25T08:30:00Z",
+      },
+    });
+
+    expect(windows).toHaveLength(2);
+    expect(windows[0]).toMatchObject({
+      provider: "anthropic",
+      label: "5h",
+      usedPercent: 23.4,
+      windowSeconds: 5 * 60 * 60,
+    });
+    expect(windows[1]).toMatchObject({
+      provider: "anthropic",
+      label: "7d",
+      usedPercent: 14.1,
+      windowSeconds: 7 * 24 * 60 * 60,
+    });
+  });
+
+  it("includes extra_usage as a currency window", () => {
+    const windows = parseAnthropicUsage({
+      five_hour: { utilization: 9, resets_at: "2026-04-22T09:00:00Z" },
+      seven_day: { utilization: 31, resets_at: "2026-04-23T23:00:00Z" },
+      extra_usage: {
+        is_enabled: true,
+        monthly_limit: 30000,
+        used_credits: 21548,
+        utilization: 71.83,
+        currency: "AUD",
+      },
+    });
+
+    const extra = windows.find((w) => w.label === "Extra (AUD)");
+    expect(extra).toBeDefined();
+    expect(extra).toMatchObject({
+      isCurrency: true,
+      usedPercent: 71.83,
+      usedValue: 215.48,
+      limitValue: 300,
+    });
+  });
+
+  it("includes per-model 7d windows when present", () => {
+    const windows = parseAnthropicUsage({
+      five_hour: { utilization: 9, resets_at: "2026-04-22T09:00:00Z" },
+      seven_day: { utilization: 31, resets_at: "2026-04-23T23:00:00Z" },
+      seven_day_sonnet: { utilization: 8, resets_at: "2026-04-23T23:00:00Z" },
+      seven_day_omelette: { utilization: 23, resets_at: "2026-04-26T23:00:00Z" },
+      seven_day_opus: null,
+    });
+
+    const sonnet = windows.find((w) => w.label === "7d Sonnet");
+    const opus = windows.find((w) => w.label === "7d Opus");
+    expect(sonnet).toMatchObject({ usedPercent: 8 });
+    expect(opus).toMatchObject({ usedPercent: 23 });
+  });
+
+  it("skips extra_usage when disabled", () => {
+    const windows = parseAnthropicUsage({
+      five_hour: { utilization: 5, resets_at: "2026-04-22T09:00:00Z" },
+      seven_day: { utilization: 10, resets_at: "2026-04-23T23:00:00Z" },
+      extra_usage: { is_enabled: false },
+    });
+    expect(windows.find((w) => w.label.startsWith("Extra"))).toBeUndefined();
+  });
+});
+
+describe("parseCodexUsage", () => {
+  it("maps primary and secondary windows from wham usage", () => {
+    const windows = parseCodexUsage({
+      plan_type: "plus",
+      rate_limit: {
+        primary_window: {
+          used_percent: 27,
+          reset_at: 1776880800,
+          limit_window_seconds: 18000,
+        },
+        secondary_window: {
+          used_percent: 11,
+          reset_at: 1777485600,
+          limit_window_seconds: 604800,
+        },
+      },
+    });
+
+    expect(windows).toHaveLength(2);
+    expect(windows[0]).toMatchObject({
+      provider: "openai-codex",
+      label: "5h",
+      usedPercent: 27,
+      windowSeconds: 18000,
+    });
+    expect(windows[1]).toMatchObject({
+      provider: "openai-codex",
+      label: "7d",
+      usedPercent: 11,
+      windowSeconds: 604800,
+    });
+  });
+
+  it("handles alternate field names", () => {
+    const windows = parseCodexUsage({
+      rate_limits: {
+        five_hour_limit: {
+          percent_left: 61,
+          reset_time_ms: 1776880800000,
+          limit_window_seconds: 18000,
+        },
+        weekly_limit: {
+          percent_left: 83,
+          reset_time_ms: 1777485600000,
+          limit_window_seconds: 604800,
+        },
+      },
+    });
+
+    expect(windows[0]).toMatchObject({ usedPercent: 39, label: "5h" });
+    expect(windows[1]).toMatchObject({ usedPercent: 17, label: "7d" });
+  });
+
+  it("includes credits window when balance is present", () => {
+    const windows = parseCodexUsage({
+      plan_type: "team",
+      rate_limit: {
+        primary_window: { used_percent: 10, reset_at: 1776880800, limit_window_seconds: 18000 },
+      },
+      credits: {
+        has_credits: true,
+        unlimited: false,
+        balance: 4200,
+        approx_local_messages: 840,
+        approx_cloud_messages: 168,
+      },
+    });
+
+    const credit = windows.find((w) => w.label === "Credits");
+    expect(credit).toBeDefined();
+    expect(credit).toMatchObject({ isCurrency: true, usedValue: 4200 });
+  });
+
+  it("includes spend control status", () => {
+    const windows = parseCodexUsage({
+      plan_type: "team",
+      rate_limit: {
+        primary_window: { used_percent: 10, reset_at: 1776880800, limit_window_seconds: 18000 },
+      },
+      spend_control: { reached: true },
+    });
+
+    const sc = windows.find((w) => w.label === "Spend cap");
+    expect(sc).toBeDefined();
+    expect(sc).toMatchObject({ limited: true, usedPercent: 100 });
+  });
+
+  it("skips credits when no balance", () => {
+    const windows = parseCodexUsage({
+      rate_limit: {
+        primary_window: { used_percent: 10, reset_at: 1776880800, limit_window_seconds: 18000 },
+      },
+      credits: { has_credits: false, balance: null },
+    });
+    expect(windows.find((w) => w.label === "Credits")).toBeUndefined();
+  });
+});
+
+describe("parseGitHubCopilotUsage", () => {
+  it("maps premium interaction quota snapshot", () => {
+    const windows = parseGitHubCopilotUsage({
+      copilot_plan: "pro",
+      quota_reset_date: "2026-05-01T00:00:00Z",
+      quota_snapshots: {
+        premium_interactions: {
+          entitlement: 300,
+          remaining: 240,
+          percent_remaining: 80,
+          quota_id: "premium",
+        },
+        chat: {
+          entitlement: 1000,
+          remaining: 950,
+          percent_remaining: 95,
+          quota_id: "chat",
+        },
+      },
+    });
+
+    expect(windows).toHaveLength(2);
+    expect(windows[0]).toMatchObject({
+      provider: "github-copilot",
+      label: "Premium / month",
+      usedPercent: 20,
+      usedValue: 60,
+      limitValue: 300,
+    });
+    expect(windows[1]).toMatchObject({
+      provider: "github-copilot",
+      label: "Chat / month",
+      usedPercent: 5,
+      usedValue: 50,
+      limitValue: 1000,
+    });
+  });
+
+  it("includes overage info on premium interactions", () => {
+    const windows = parseGitHubCopilotUsage({
+      copilot_plan: "business",
+      quota_reset_date: "2026-05-01T00:00:00Z",
+      quota_snapshots: {
+        premium_interactions: {
+          entitlement: 300,
+          remaining: 293,
+          percent_remaining: 97.8,
+          overage_count: 5,
+          overage_permitted: true,
+        },
+      },
+    });
+
+    const premium = windows.find((w) => w.label === "Premium / month");
+    expect(premium).toBeDefined();
+    expect(premium!.nextAmount).toBe("+5 overage");
+  });
+
+  it("handles free-tier completions data", () => {
+    const windows = parseGitHubCopilotUsage({
+      access_type_sku: "free_limited_copilot",
+      limited_user_reset_date: "2026-05-01",
+      monthly_quotas: {
+        chat: 500,
+        completions: 4000,
+      },
+      limited_user_quotas: {
+        chat: 410,
+        completions: 4000,
+      },
+    });
+
+    expect(windows).toHaveLength(2);
+    expect(windows[0]).toMatchObject({ label: "Chat / month", usedPercent: 18 });
+    expect(windows[1]).toMatchObject({ label: "Completions / month", usedPercent: 0 });
+  });
+});

package/src/providers/providers.ts

@@ -0,0 +1,245 @@
+import type { QuotaWindow } from "../types/quotas.js";
+import { safePercent } from "../utils/quotas-severity.js";
+
+function parseDateish(value: unknown): Date {
+  if (typeof value === "number") {
+    const ms = value > 10 ** 11 ? value : value * 1000;
+    return new Date(ms);
+  }
+  if (typeof value === "string") return new Date(value);
+  return new Date(0);
+}
+
+function monthWindowSeconds(resetAt: Date): number {
+  const approxStart = new Date(resetAt);
+  approxStart.setMonth(approxStart.getMonth() - 1);
+  return Math.max(1, Math.round((resetAt.getTime() - approxStart.getTime()) / 1000));
+}
+
+export function parseAnthropicUsage(data: any): QuotaWindow[] {
+  const windows: QuotaWindow[] = [];
+
+  if (data?.five_hour) {
+    windows.push({
+      provider: "anthropic",
+      label: "5h",
+      usedPercent: Number(data.five_hour.utilization ?? 0),
+      resetsAt: parseDateish(data.five_hour.resets_at),
+      windowSeconds: 5 * 60 * 60,
+      usedValue: Number(data.five_hour.utilization ?? 0),
+      limitValue: 100,
+      showPace: false,
+      nextLabel: "Resets",
+    });
+  }
+
+  if (data?.seven_day) {
+    windows.push({
+      provider: "anthropic",
+      label: "7d",
+      usedPercent: Number(data.seven_day.utilization ?? 0),
+      resetsAt: parseDateish(data.seven_day.resets_at),
+      windowSeconds: 7 * 24 * 60 * 60,
+      usedValue: Number(data.seven_day.utilization ?? 0),
+      limitValue: 100,
+      showPace: false,
+      nextLabel: "Resets",
+    });
+  }
+
+  // Per-model 7d windows
+  const modelWindows: Array<[string, string]> = [
+    ["seven_day_sonnet", "7d Sonnet"],
+    ["seven_day_omelette", "7d Opus"],
+    ["seven_day_opus", "7d Opus (legacy)"],
+  ];
+  for (const [key, label] of modelWindows) {
+    const entry = data?.[key];
+    if (entry && typeof entry === "object" && entry.utilization != null) {
+      windows.push({
+        provider: "anthropic",
+        label,
+        usedPercent: Number(entry.utilization),
+        resetsAt: parseDateish(entry.resets_at),
+        windowSeconds: 7 * 24 * 60 * 60,
+        usedValue: Number(entry.utilization),
+        limitValue: 100,
+        showPace: false,
+        nextLabel: "Resets",
+      });
+    }
+  }
+
+  // Extra usage (overage budget)
+  const extra = data?.extra_usage;
+  if (extra && extra.is_enabled && extra.monthly_limit > 0) {
+    const limitDollars = extra.monthly_limit / 100;
+    const usedDollars = (extra.used_credits ?? 0) / 100;
+    const currency = extra.currency ?? "USD";
+    windows.push({
+      provider: "anthropic",
+      label: `Extra (${currency})`,
+      usedPercent: Number(extra.utilization ?? safePercent(usedDollars, limitDollars)),
+      resetsAt: new Date(new Date().getFullYear(), new Date().getMonth() + 1, 1),
+      windowSeconds: 30 * 24 * 60 * 60,
+      usedValue: usedDollars,
+      limitValue: limitDollars,
+      isCurrency: true,
+      showPace: true,
+      paceScale: 1,
+      nextLabel: "Resets",
+    });
+  }
+
+  return windows;
+}
+
+function percentLeftToUsedPercent(limit: any): number {
+  if (limit?.percent_left != null) return Math.max(0, 100 - Number(limit.percent_left));
+  if (limit?.remaining_percent != null) return Math.max(0, 100 - Number(limit.remaining_percent));
+  if (limit?.used_percent != null) return Number(limit.used_percent);
+  return 0;
+}
+
+export function parseCodexUsage(data: any): QuotaWindow[] {
+  const rateLimit = data?.rate_limit ?? data?.rate_limits ?? {};
+  const primary = rateLimit.primary_window ?? rateLimit.primary ?? rateLimit.five_hour_limit ?? rateLimit.five_hour;
+  const secondary = rateLimit.secondary_window ?? rateLimit.secondary ?? rateLimit.weekly_limit ?? rateLimit.weekly;
+
+  const windows: QuotaWindow[] = [];
+
+  if (primary) {
+    windows.push({
+      provider: "openai-codex",
+      label: "5h",
+      usedPercent: percentLeftToUsedPercent(primary),
+      resetsAt: parseDateish(primary.reset_at ?? primary.reset_time_ms),
+      windowSeconds: Number(primary.limit_window_seconds ?? 5 * 60 * 60),
+      usedValue: percentLeftToUsedPercent(primary),
+      limitValue: 100,
+      showPace: false,
+      nextLabel: "Resets",
+    });
+  }
+
+  if (secondary) {
+    windows.push({
+      provider: "openai-codex",
+      label: "7d",
+      usedPercent: percentLeftToUsedPercent(secondary),
+      resetsAt: parseDateish(secondary.reset_at ?? secondary.reset_time_ms),
+      windowSeconds: Number(secondary.limit_window_seconds ?? 7 * 24 * 60 * 60),
+      usedValue: percentLeftToUsedPercent(secondary),
+      limitValue: 100,
+      showPace: false,
+      nextLabel: "Resets",
+    });
+  }
+
+  // Credits balance
+  const credits = data?.credits;
+  if (credits && credits.has_credits && credits.balance != null) {
+    const balance = Number(credits.balance);
+    windows.push({
+      provider: "openai-codex",
+      label: "Credits",
+      usedPercent: 0,
+      resetsAt: new Date(0),
+      windowSeconds: 0,
+      usedValue: balance,
+      limitValue: balance,
+      isCurrency: true,
+      showPace: false,
+      nextLabel: credits.approx_local_messages
+        ? `~${credits.approx_local_messages} local msgs`
+        : undefined,
+    });
+  }
+
+  // Spend control
+  const spendControl = data?.spend_control;
+  if (spendControl) {
+    const reached = !!spendControl.reached;
+    windows.push({
+      provider: "openai-codex",
+      label: "Spend cap",
+      usedPercent: reached ? 100 : 0,
+      resetsAt: new Date(0),
+      windowSeconds: 0,
+      usedValue: reached ? 1 : 0,
+      limitValue: 1,
+      limited: reached,
+      showPace: false,
+      nextLabel: reached ? "Reached" : "OK",
+    });
+  }
+
+  return windows;
+}
+
+export function parseGitHubCopilotUsage(data: any): QuotaWindow[] {
+  const windows: QuotaWindow[] = [];
+
+  const resetAt = parseDateish(data?.quota_reset_date ?? data?.quota_reset_date_utc ?? data?.limited_user_reset_date);
+  const periodSeconds = monthWindowSeconds(resetAt);
+
+  const snapshots = data?.quota_snapshots;
+  if (snapshots && typeof snapshots === "object") {
+    const mappings: Array<[string, string]> = [
+      ["premium_interactions", "Premium / month"],
+      ["chat", "Chat / month"],
+      ["completions", "Completions / month"],
+    ];
+
+    for (const [key, label] of mappings) {
+      const snap = snapshots[key];
+      if (!snap || snap.unlimited) continue;
+      const entitlement = Number(snap.entitlement ?? 0);
+      const remaining = Number(snap.remaining ?? snap.quota_remaining ?? 0);
+      if (entitlement <= 0) continue;
+      const overageCount = Number(snap.overage_count ?? 0);
+      const overagePermitted = !!snap.overage_permitted;
+      windows.push({
+        provider: "github-copilot",
+        label,
+        usedPercent: safePercent(entitlement - remaining, entitlement),
+        resetsAt: resetAt,
+        windowSeconds: periodSeconds,
+        usedValue: entitlement - remaining,
+        limitValue: entitlement,
+        showPace: true,
+        nextLabel: "Resets",
+        nextAmount: overageCount > 0
+          ? `+${overageCount} overage`
+          : overagePermitted
+            ? "overage allowed"
+            : undefined,
+      });
+    }
+    return windows;
+  }
+
+  if (data?.monthly_quotas && data?.limited_user_quotas) {
+    for (const [key, label] of [
+      ["chat", "Chat / month"],
+      ["completions", "Completions / month"],
+    ] as const) {
+      const limitValue = Number(data.monthly_quotas[key] ?? 0);
+      const remaining = Number(data.limited_user_quotas[key] ?? 0);
+      if (limitValue <= 0) continue;
+      windows.push({
+        provider: "github-copilot",
+        label,
+        usedPercent: safePercent(limitValue - remaining, limitValue),
+        resetsAt: resetAt,
+        windowSeconds: periodSeconds,
+        usedValue: limitValue - remaining,
+        limitValue,
+        showPace: true,
+        nextLabel: "Resets",
+      });
+    }
+  }
+
+  return windows;
+}

package/src/types/quotas.ts

@@ -0,0 +1,31 @@
+export type SupportedQuotaProvider =
+  | "anthropic"
+  | "openai-codex"
+  | "github-copilot";
+
+export type QuotasErrorKind =
+  | "cancelled"
+  | "timeout"
+  | "config"
+  | "http"
+  | "network";
+
+export type QuotasResult =
+  | { success: true; data: { windows: QuotaWindow[]; provider: SupportedQuotaProvider } }
+  | { success: false; error: { message: string; kind: QuotasErrorKind } };
+
+export interface QuotaWindow {
+  provider: SupportedQuotaProvider;
+  label: string;
+  usedPercent: number;
+  resetsAt: Date;
+  windowSeconds: number;
+  usedValue: number;
+  limitValue: number;
+  isCurrency?: boolean;
+  showPace?: boolean;
+  paceScale?: number;
+  limited?: boolean;
+  nextAmount?: string;
+  nextLabel?: string;
+}

package/src/utils/quotas-severity.test.ts

@@ -0,0 +1,111 @@
+import { assert, describe, expect, it } from "vitest";
+import {
+  assessWindow,
+  getPacePercent,
+  getProjectedPercent,
+  getSeverityColor,
+  type QuotaWindow,
+  safePercent,
+} from "./quotas-severity.js";
+
+function makeWindow(
+  overrides: Partial<QuotaWindow> & Pick<QuotaWindow, "usedPercent">,
+): QuotaWindow {
+  const windowSeconds = overrides.windowSeconds ?? 3600;
+  const resetsAt =
+    overrides.resetsAt ?? new Date(Date.now() + windowSeconds * 500);
+  return {
+    provider: "anthropic",
+    label: "Test Window",
+    resetsAt,
+    windowSeconds,
+    usedValue: 0,
+    limitValue: 100,
+    ...overrides,
+  };
+}
+
+describe("safePercent", () => {
+  it("returns 0 for zero/invalid limit", () => {
+    expect(safePercent(50, 0)).toBe(0);
+    expect(safePercent(50, -1)).toBe(0);
+    expect(safePercent(50, NaN)).toBe(0);
+    expect(safePercent(NaN, 100)).toBe(0);
+  });
+
+  it("computes correct percentage", () => {
+    expect(safePercent(50, 100)).toBe(50);
+    expect(safePercent(75, 100)).toBe(75);
+    expect(safePercent(1, 3)).toBeCloseTo(33.33);
+  });
+});
+
+describe("getPacePercent", () => {
+  it("returns null for zero window", () => {
+    const w = makeWindow({ usedPercent: 50, windowSeconds: 0 });
+    expect(getPacePercent(w)).toBeNull();
+  });
+
+  it("returns ~50 for a window 50% elapsed", () => {
+    const w = makeWindow({
+      usedPercent: 50,
+      windowSeconds: 3600,
+      resetsAt: new Date(Date.now() + 1800 * 1000),
+    });
+    const pace = getPacePercent(w);
+    assert(pace, "pace should not be null");
+    expect(pace).toBeCloseTo(50, 0);
+  });
+});
+
+describe("getProjectedPercent", () => {
+  it("returns usedPercent when no pace", () => {
+    expect(getProjectedPercent(42, null)).toBe(42);
+  });
+
+  it("projects based on pace", () => {
+    expect(getProjectedPercent(50, 25)).toBe(200);
+  });
+});
+
+describe("assessWindow", () => {
+  it("returns critical for limited window regardless of usage", () => {
+    const w = makeWindow({ usedPercent: 5, showPace: false, limited: true });
+    expect(assessWindow(w).severity).toBe("critical");
+  });
+
+  it("returns warning when projected exceeds dynamic warn threshold", () => {
+    const w = makeWindow({
+      usedPercent: 95,
+      showPace: true,
+      paceScale: 1,
+      windowSeconds: 3600,
+      resetsAt: new Date(Date.now() + 1800 * 1000),
+    });
+    expect(assessWindow(w).severity).toBe("warning");
+  });
+
+  it("uses paceScale to normalize pace", () => {
+    const w = makeWindow({
+      usedPercent: 95,
+      showPace: true,
+      paceScale: 1 / 7,
+      windowSeconds: 7 * 24 * 3600,
+      resetsAt: new Date(Date.now() + 6 * 24 * 3600 * 1000),
+    });
+    const result = assessWindow(w);
+    assert(result.pacePercent, "pacePercent should not be null");
+    expect(result.pacePercent).toBeLessThan(15);
+    expect(result.projectedPercent).toBeGreaterThan(500);
+    expect(result.severity).toBe("critical");
+  });
+});
+
+describe("getSeverityColor", () => {
+  it("maps severity levels to display colors", () => {
+    expect(getSeverityColor("none")).toBe("success");
+    expect(getSeverityColor("warning")).toBe("warning");
+    expect(getSeverityColor("high")).toBe("error");
+    expect(getSeverityColor("critical")).toBe("error");
+  });
+});