@latentminds/pi-quotas 0.1.1 → 0.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @latentminds/pi-quotas
 
-Quota monitoring for the [Pi coding agent](https://github.com/mariozechner/pi). Shows remaining usage and rate limits for Anthropic, OpenAI Codex, and GitHub Copilot — directly in your Pi session.
+Quota monitoring for the [Pi coding agent](https://github.com/mariozechner/pi). Shows remaining usage and rate limits for Anthropic, OpenAI Codex, GitHub Copilot, and OpenRouter — directly in your Pi session.
 
 ## Screenshots
 
@@ -37,6 +37,7 @@ pi -e npm:@latentminds/pi-quotas
 | `/anthropic:quotas` | Anthropic quotas only |
 | `/codex:quotas` | OpenAI Codex quotas only |
 | `/github:quotas` | GitHub Copilot quotas only |
+| `/openrouter:quotas` | OpenRouter quotas only |
 | `/quotas:settings` | Toggle individual features on or off |
 
 ## Features
@@ -47,7 +48,7 @@ Run `/quotas` to open a bordered TUI view showing all providers side by side, wi
 
 ### Footer status widget
 
-When your active model is from a supported provider, the Pi footer shows real-time quota headroom — updated every 60 seconds and on each turn. Colours shift from green → amber → red as usage climbs.
+When your active model is from a supported provider, the Pi footer shows real-time quota headroom - updated every 60 seconds and on each turn. Colours shift from green → amber → red as usage climbs.
 
 ### Quota warnings
 
@@ -57,7 +58,7 @@ Automatic notifications when projected usage is on track to exceed limits before
 
 Use `/quotas:settings` to enable or disable:
 - Combined `/quotas` command
-- Per-provider commands (`/anthropic:quotas`, `/codex:quotas`, `/github:quotas`)
+- Per-provider commands (`/anthropic:quotas`, `/codex:quotas`, `/github:quotas`, `/openrouter:quotas`)
 - Footer status widget
 - Quota warning notifications
 
@@ -70,6 +71,7 @@ Settings can be saved globally (`~/.pi/agent/extensions/quotas.json`) or per-pro
 | Anthropic | 5h, 7d, per-model 7d, extra usage | Utilization percentages; optional overage budget in local currency |
 | OpenAI Codex | 5h, 7d, credits, spend cap | Rate-limit percentages; credit balance; spend-cap reached/OK |
 | GitHub Copilot | Premium/chat/completions per month | Remaining/entitlement counts with overage indicators |
+| OpenRouter | Monthly budget, daily/weekly/monthly usage | USD spending tracking with cents precision; optional per-key budget limits; UTC-based period resets |
 
 ## Credentials
 
@@ -78,17 +80,26 @@ pi-quotas reads existing Pi auth entries from `~/.pi/agent/auth.json`:
 - `anthropic` — Anthropic OAuth token
 - `openai-codex` — Codex access token (also reads `~/.codex/auth.json` for the account ID)
 - `github-copilot` — GitHub Copilot OAuth token (falls back to `gh auth token` if needed)
+- `openrouter` — OpenRouter API key (Bearer token)
 
-No additional setup is required — if Pi can use the provider, pi-quotas can check its quotas.
+No additional setup is required - if Pi can use the provider, pi-quotas can check its quotas.
 
 ## Requirements
 
 - [Pi](https://github.com/mariozechner/pi) >= 0.61.0
 
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release notes and recent changes.
+
 ## License
 
 [MIT](LICENSE) © Latent Minds Pty Ltd
 
+## Acknowledgements
+
+This project was inspired by [@aliou/pi-synthetic](https://www.npmjs.com/package/@aliou/pi-synthetic).
+
 <p align="center">
   <img src="docs/latent-minds@2x.png" alt="Latent Minds" width="320" />
 </p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@latentminds/pi-quotas",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "private": false,

package/src/extensions/command-quotas/command.ts

@@ -65,7 +65,7 @@ async function openQuotaView(
 
 export function registerQuotasCommands(pi: ExtensionAPI): void {
   pi.registerCommand("quotas", {
-    description: "Display remaining quotas for Anthropic, Codex, and GitHub Copilot",
+    description: "Display remaining quotas for Anthropic, Codex, GitHub Copilot, and OpenRouter",
     handler: async (_args, ctx) => {
       if (!configLoader.getConfig().quotasCommand) {
         ctx.ui.notify("/quotas is disabled. Re-enable it in /quotas:settings.", "warning");

package/src/extensions/command-quotas/components/quotas-display.ts

@@ -162,7 +162,12 @@ export class QuotasComponent implements Component {
       // Format the usage string depending on window type
       let usedStr: string;
       if (window.isCurrency) {
-        usedStr = `$${window.usedValue.toFixed(2)} / $${window.limitValue.toFixed(2)}`;
+        // Tracking-only windows have limitValue=0, show just usage
+        if (window.limitValue === 0) {
+          usedStr = `$${window.usedValue.toFixed(2)} used`;
+        } else {
+          usedStr = `$${window.usedValue.toFixed(2)} / $${window.limitValue.toFixed(2)}`;
+        }
       } else if (window.limitValue <= 1 && window.label === "Spend cap") {
         usedStr = window.limited ? "REACHED" : "OK";
       } else if (window.limitValue > 0 && window.limitValue !== 100) {

package/src/extensions/command-quotas/provider-commands.test.ts

@@ -31,4 +31,13 @@ describe("getProviderCommandInfo", () => {
       title: "GitHub Copilot Quotas",
     });
   });
+
+  it("maps openrouter to openrouter:quotas", () => {
+    const info = getProviderCommandInfo("openrouter");
+    expect(info).toMatchObject<Partial<ProviderCommandInfo>>({
+      provider: "openrouter",
+      commandName: "openrouter:quotas",
+      title: "OpenRouter Quotas",
+    });
+  });
 });

package/src/extensions/command-quotas/provider-commands.ts

@@ -28,5 +28,11 @@ export function getProviderCommandInfo(
         commandName: "github:quotas",
         title: "GitHub Copilot Quotas",
       };
+    case "openrouter":
+      return {
+        provider,
+        commandName: "openrouter:quotas",
+        title: "OpenRouter Quotas",
+      };
   }
 }

package/src/extensions/usage-status/format-status.test.ts

@@ -53,7 +53,7 @@ describe("formatWindowStatus", () => {
       limitValue: 300,
     };
     const result = formatWindowStatus(theme, w);
-    expect(result).toContain("$215/$300");
+    expect(result).toContain("$215.00/$300.00");
     expect(result).toContain("[warning]");
   });
 

package/src/extensions/usage-status/format-status.ts

@@ -31,6 +31,12 @@ const SHORT_LABELS: Record<string, string> = {
   "Extra (USD)": "extra",
   "Extra (EUR)": "extra",
   "Extra (GBP)": "extra",
+  // OpenRouter labels
+  "Monthly Budget": "budget",
+  "Credits Remaining": "credits",
+  "Daily": "daily",
+  "Weekly": "weekly",
+  "Monthly": "monthly",
 };
 
 /**
@@ -66,7 +72,12 @@ export function formatWindowStatus(theme: ThemeLike, w: WindowStatus): string {
   if (w.label === "Spend cap") {
     valueText = theme.fg(color, w.limited ? "REACHED" : "OK");
   } else if (w.isCurrency && w.usedValue != null && w.limitValue != null) {
-    valueText = theme.fg(color, `$${w.usedValue.toFixed(0)}/$${w.limitValue.toFixed(0)}`);
+    // Tracking-only windows have limitValue=0, show just usage
+    if (w.limitValue === 0) {
+      valueText = theme.fg(color, `$${w.usedValue.toFixed(2)} used`);
+    } else {
+      valueText = theme.fg(color, `$${w.usedValue.toFixed(2)}/$${w.limitValue.toFixed(2)}`);
+    }
   } else if (hasRealCounts(w)) {
     const remaining = Math.max(0, Math.round(w.limitValue! - w.usedValue!));
     valueText = theme.fg(color, `${remaining}/${w.limitValue}`);

package/src/lib/quotas.ts

@@ -6,18 +6,21 @@ export const SUPPORTED_PROVIDERS: SupportedQuotaProvider[] = [
   "anthropic",
   "openai-codex",
   "github-copilot",
+  "openrouter",
 ];
 
 export const PROVIDER_LABELS: Record<SupportedQuotaProvider, string> = {
   anthropic: "Anthropic",
   "openai-codex": "OpenAI Codex",
   "github-copilot": "GitHub Copilot",
+  openrouter: "OpenRouter",
 };
 
 const PROVIDER_TTLS_MS: Record<SupportedQuotaProvider, number> = {
   anthropic: 5 * 60_000,
   "openai-codex": 60_000,
   "github-copilot": 5 * 60_000,
+  openrouter: 60_000,
 };
 
 type CacheEntry = {

package/src/providers/fetch.test.ts

@@ -3,6 +3,7 @@ import {
   fetchAnthropicQuotasWithToken,
   fetchCodexQuotasWithToken,
   fetchGitHubCopilotQuotasWithToken,
+  fetchOpenRouterQuotasWithToken,
 } from "./fetch.js";
 
 const originalFetch = globalThis.fetch;
@@ -135,3 +136,62 @@ describe("fetchGitHubCopilotQuotasWithToken", () => {
     expect(globalThis.fetch).toHaveBeenCalledTimes(2);
   });
 });
+
+describe("fetchOpenRouterQuotasWithToken", () => {
+  it("returns config error when token missing", async () => {
+    const result = await fetchOpenRouterQuotasWithToken(undefined);
+    expect(result).toMatchObject({
+      success: false,
+      error: { kind: "config" },
+    });
+  });
+
+  it("fetches and parses OpenRouter key info with budget", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue(
+      new Response(
+        JSON.stringify({
+          data: {
+            label: "Test Key",
+            limit: 50,
+            limit_remaining: 35,
+            limit_reset: "monthly",
+            usage: 15,
+            usage_daily: 2.5,
+            usage_weekly: 12,
+            usage_monthly: 15,
+            byok_usage: 0,
+            byok_usage_daily: 0,
+            byok_usage_weekly: 0,
+            byok_usage_monthly: 0,
+            is_free_tier: false,
+          },
+        }),
+        { status: 200 },
+      ),
+    ) as any;
+
+    const result = await fetchOpenRouterQuotasWithToken("sk-or-test");
+    expect(result.success).toBe(true);
+    if (result.success) {
+      expect(result.data.provider).toBe("openrouter");
+      expect(result.data.windows).toHaveLength(4);
+      expect(result.data.windows[0]).toMatchObject({
+        label: "Monthly Budget",
+        usedValue: 15,
+        limitValue: 50,
+      });
+    }
+  });
+
+  it("handles HTTP error", async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue(
+      new Response("Unauthorized", { status: 401 }),
+    ) as any;
+
+    const result = await fetchOpenRouterQuotasWithToken("bad-key");
+    expect(result).toMatchObject({
+      success: false,
+      error: { kind: "http" },
+    });
+  });
+});

package/src/providers/fetch.ts

@@ -8,6 +8,7 @@ import {
   parseAnthropicUsage,
   parseCodexUsage,
   parseGitHubCopilotUsage,
+  parseOpenRouterUsage,
 } from "./providers.js";
 
 const FETCH_TIMEOUT_MS = 15_000;
@@ -238,8 +239,38 @@ export async function fetchGitHubCopilotQuotas(
   );
 }
 
+export async function fetchOpenRouterQuotasWithToken(
+  accessToken: string | undefined,
+  signal?: AbortSignal,
+): Promise<QuotasResult> {
+  if (!accessToken) return failure("No OpenRouter API key found", "config");
+  const result = await fetchJson(
+    "https://openrouter.ai/api/v1/key",
+    {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json",
+      },
+    },
+    signal,
+  );
+  if (!result.ok) return failure(result.message, result.kind);
+  return success("openrouter", parseOpenRouterUsage(result.data));
+}
+
+export async function fetchOpenRouterQuotas(
+  authStorage: AuthStorage,
+  signal?: AbortSignal,
+): Promise<QuotasResult> {
+  return fetchOpenRouterQuotasWithToken(
+    await providerAccessToken(authStorage, "openrouter"),
+    signal,
+  );
+}
+
 export const PROVIDER_FETCHERS = {
   anthropic: fetchAnthropicQuotas,
   "openai-codex": fetchCodexQuotas,
   "github-copilot": fetchGitHubCopilotQuotas,
+  openrouter: fetchOpenRouterQuotas,
 } as const;

package/src/providers/parse.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import { parseAnthropicUsage } from "./providers.js";
 import { parseCodexUsage } from "./providers.js";
 import { parseGitHubCopilotUsage } from "./providers.js";
+import { parseOpenRouterUsage } from "./providers.js";
 
 describe("parseAnthropicUsage", () => {
   it("maps oauth usage response into quota windows", () => {
@@ -254,3 +255,156 @@ describe("parseGitHubCopilotUsage", () => {
     expect(windows[1]).toMatchObject({ label: "Completions / month", usedPercent: 0 });
   });
 });
+
+describe("parseOpenRouterUsage", () => {
+  it("maps API response with monthly budget limit", () => {
+    const windows = parseOpenRouterUsage({
+      data: {
+        label: "Test Key",
+        limit: 50,
+        limit_remaining: 35,
+        limit_reset: "monthly",
+        usage: 15,
+        usage_daily: 2.5,
+        usage_weekly: 12,
+        usage_monthly: 15,
+        byok_usage: 0,
+        byok_usage_daily: 0,
+        byok_usage_weekly: 0,
+        byok_usage_monthly: 0,
+        creator_user_id: "user123",
+        include_byok_in_limit: false,
+        is_free_tier: false,
+        is_management_key: false,
+        is_provisioning_key: false,
+      },
+    });
+
+    // When limit is set, we get: Monthly Budget + Daily + Weekly + Monthly = 4 windows
+    expect(windows).toHaveLength(4);
+
+    // Monthly Budget window
+    const budget = windows.find((w) => w.label === "Monthly Budget");
+    expect(budget).toBeDefined();
+    expect(budget).toMatchObject({
+      provider: "openrouter",
+      label: "Monthly Budget",
+      usedPercent: 30, // 15/50 = 30%
+      isCurrency: true,
+      usedValue: 15,
+      limitValue: 50,
+      showPace: true,
+    });
+
+    // Daily, Weekly, Monthly usage windows
+    expect(windows.find((w) => w.label === "Daily")).toBeDefined();
+    expect(windows.find((w) => w.label === "Weekly")).toBeDefined();
+    expect(windows.find((w) => w.label === "Monthly")).toBeDefined();
+  });
+
+  it("maps unlimited key with remaining credits", () => {
+    const windows = parseOpenRouterUsage({
+      data: {
+        label: "Unlimited Key",
+        limit: null,
+        limit_remaining: 100,
+        limit_reset: null,
+        usage: 50,
+        usage_daily: 5,
+        usage_weekly: 20,
+        usage_monthly: 50,
+        byok_usage: 0,
+        byok_usage_daily: 0,
+        byok_usage_weekly: 0,
+        byok_usage_monthly: 0,
+        creator_user_id: "user123",
+        include_byok_in_limit: false,
+        is_free_tier: false,
+        is_management_key: false,
+        is_provisioning_key: false,
+      },
+    });
+
+    // When unlimited with limit_remaining: Credits Remaining + Daily + Weekly + Monthly = 4 windows
+    expect(windows).toHaveLength(4);
+
+    // Credits Remaining window
+    const remaining = windows.find((w) => w.label === "Credits Remaining");
+    expect(remaining).toBeDefined();
+    expect(remaining).toMatchObject({
+      provider: "openrouter",
+      label: "Credits Remaining",
+      usedPercent: 0,
+      isCurrency: true,
+      usedValue: 100,
+      limitValue: 100,
+      showPace: false,
+    });
+  });
+
+  it("handles zero usage", () => {
+    const windows = parseOpenRouterUsage({
+      data: {
+        label: "Test Key",
+        limit: 100,
+        limit_remaining: 100,
+        limit_reset: "monthly",
+        usage: 0,
+        usage_daily: 0,
+        usage_weekly: 0,
+        usage_monthly: 0,
+        byok_usage: 0,
+        byok_usage_daily: 0,
+        byok_usage_weekly: 0,
+        byok_usage_monthly: 0,
+        creator_user_id: "user123",
+        include_byok_in_limit: false,
+        is_free_tier: false,
+        is_management_key: false,
+        is_provisioning_key: false,
+      },
+    });
+
+    const budget = windows.find((w) => w.label === "Monthly Budget");
+    expect(budget).toBeDefined();
+    expect(budget!.usedPercent).toBe(0);
+  });
+
+  it("returns empty array when no data", () => {
+    const windows = parseOpenRouterUsage({});
+    expect(windows).toHaveLength(0);
+  });
+
+  it("handles missing limit_remaining for unlimited keys", () => {
+    const windows = parseOpenRouterUsage({
+      data: {
+        label: "Test Key",
+        limit: null,
+        limit_remaining: null,
+        limit_reset: null,
+        usage: 25,
+        usage_daily: 3,
+        usage_weekly: 10,
+        usage_monthly: 25,
+        byok_usage: 0,
+        byok_usage_daily: 0,
+        byok_usage_weekly: 0,
+        byok_usage_monthly: 0,
+        creator_user_id: "user123",
+        include_byok_in_limit: false,
+        is_free_tier: false,
+        is_management_key: false,
+        is_provisioning_key: false,
+      },
+    });
+
+    // Should not have "Credits Remaining" window if limit_remaining is null
+    const remaining = windows.find((w) => w.label === "Credits Remaining");
+    expect(remaining).toBeUndefined();
+
+    // But should still have usage tracking windows
+    expect(windows.find((w) => w.label === "Daily")).toBeDefined();
+    expect(windows.find((w) => w.label === "Weekly")).toBeDefined();
+    expect(windows.find((w) => w.label === "Monthly")).toBeDefined();
+  });
+});

package/src/providers/providers.ts

@@ -243,3 +243,112 @@ export function parseGitHubCopilotUsage(data: any): QuotaWindow[] {
 
   return windows;
 }
+
+// Helper functions for OpenRouter date calculations (UTC-based)
+function calculateNextMidnightUTC(): Date {
+  const now = new Date();
+  const midnight = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1, 0, 0, 0));
+  return midnight;
+}
+
+function calculateNextMondayUTC(): Date {
+  const now = new Date();
+  const day = now.getUTCDay(); // 0 = Sunday, 1 = Monday, etc.
+  const daysUntilMonday = day === 0 ? 1 : (8 - day); // Days until next Monday
+  const monday = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + daysUntilMonday, 0, 0, 0));
+  return monday;
+}
+
+function calculateNextMonthStartUTC(): Date {
+  const now = new Date();
+  return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1, 0, 0, 0));
+}
+
+export function parseOpenRouterUsage(data: any): QuotaWindow[] {
+  const windows: QuotaWindow[] = [];
+  const keyData = data?.data;
+
+  if (!keyData) return windows;
+
+  const limit = keyData.limit;
+  const limitRemaining = keyData.limit_remaining;
+  const usageDaily = keyData.usage_daily ?? 0;
+  const usageWeekly = keyData.usage_weekly ?? 0;
+  const usageMonthly = keyData.usage_monthly ?? 0;
+
+  // Monthly budget window (if limit is set)
+  if (limit != null && limit > 0) {
+    const usedPercent = safePercent(usageMonthly, limit);
+    windows.push({
+      provider: "openrouter",
+      label: "Monthly Budget",
+      usedPercent,
+      resetsAt: calculateNextMonthStartUTC(),
+      windowSeconds: 30 * 24 * 60 * 60,
+      usedValue: usageMonthly,
+      limitValue: limit,
+      isCurrency: true,
+      showPace: true,
+      paceScale: 1,
+      nextLabel: "Resets",
+    });
+  } else if (limitRemaining != null && limitRemaining >= 0) {
+    // Unlimited key with remaining tracked
+    windows.push({
+      provider: "openrouter",
+      label: "Credits Remaining",
+      usedPercent: 0,
+      resetsAt: new Date(0),
+      windowSeconds: 0,
+      usedValue: limitRemaining,
+      limitValue: limitRemaining,
+      isCurrency: true,
+      showPace: false,
+      nextLabel: undefined,
+    });
+  }
+
+  // Daily usage window (tracking only)
+  windows.push({
+    provider: "openrouter",
+    label: "Daily",
+    usedPercent: 0,
+    resetsAt: calculateNextMidnightUTC(),
+    windowSeconds: 24 * 60 * 60,
+    usedValue: usageDaily,
+    limitValue: 0,
+    isCurrency: true,
+    showPace: false,
+    nextLabel: "UTC",
+  });
+
+  // Weekly usage window (tracking only)
+  windows.push({
+    provider: "openrouter",
+    label: "Weekly",
+    usedPercent: 0,
+    resetsAt: calculateNextMondayUTC(),
+    windowSeconds: 7 * 24 * 60 * 60,
+    usedValue: usageWeekly,
+    limitValue: 0,
+    isCurrency: true,
+    showPace: false,
+    nextLabel: "Week",
+  });
+
+  // Monthly usage window (tracking only)
+  windows.push({
+    provider: "openrouter",
+    label: "Monthly",
+    usedPercent: 0,
+    resetsAt: calculateNextMonthStartUTC(),
+    windowSeconds: 30 * 24 * 60 * 60,
+    usedValue: usageMonthly,
+    limitValue: 0,
+    isCurrency: true,
+    showPace: false,
+    nextLabel: "Month",
+  });
+
+  return windows;
+}

package/src/types/quotas.ts

@@ -1,7 +1,8 @@
 export type SupportedQuotaProvider =
   | "anthropic"
   | "openai-codex"
-  | "github-copilot";
+  | "github-copilot"
+  | "openrouter";
 
 export type QuotasErrorKind =
   | "cancelled"