offrouter-core 0.0.0

package/src/usage.test.ts

@@ -0,0 +1,283 @@
+import { describe, expect, it } from "vitest";
+import {
+  InMemoryStateStore,
+  InMemoryUsageStore,
+  type UsageEvent,
+} from "./usage.js";
+
+function err(
+  providerId: string,
+  kind: UsageEvent["kind"] = "request_error",
+  at?: Date,
+): UsageEvent {
+  return {
+    providerId,
+    authTier: "subscription",
+    kind,
+    at,
+  };
+}
+
+describe("InMemoryUsageStore", () => {
+  it("applies concurrent usage updates without losing counters", async () => {
+    const store = new InMemoryUsageStore();
+    const providerId = "claude";
+
+    await Promise.all(
+      Array.from({ length: 50 }, () =>
+        store.record({
+          providerId,
+          authTier: "subscription",
+          kind: "subscription_usage",
+          amount: 1,
+        }),
+      ),
+    );
+
+    const snap = await store.getProvider(providerId);
+    expect(snap?.subscriptionQuotaUsed).toBe(50);
+    expect(snap?.successCount).toBe(50);
+  });
+
+  it("tracks quota remaining for subscription capacity", async () => {
+    const store = new InMemoryUsageStore();
+    await store.setSubscriptionQuota("claude", {
+      limit: 100,
+      used: 40,
+      status: "active",
+    });
+
+    let snap = await store.getProvider("claude");
+    expect(snap?.subscriptionQuotaLimit).toBe(100);
+    expect(snap?.subscriptionQuotaUsed).toBe(40);
+    expect(snap?.subscriptionQuotaRemaining).toBe(60);
+    expect(snap?.subscriptionStatus).toBe("active");
+    expect(snap?.health).toBe("healthy");
+
+    await store.record({
+      providerId: "claude",
+      authTier: "subscription",
+      kind: "subscription_usage",
+      amount: 25,
+    });
+
+    snap = await store.getProvider("claude");
+    expect(snap?.subscriptionQuotaUsed).toBe(65);
+    expect(snap?.subscriptionQuotaRemaining).toBe(35);
+  });
+
+  it("downgrades provider health via sliding-window error budget and cooldown", async () => {
+    const t0 = Date.UTC(2026, 0, 1, 12, 0, 0);
+    let nowMs = t0;
+    const store = new InMemoryUsageStore({
+      windowMs: 10_000,
+      healthyMaxErrors: 2,
+      deadMinErrors: 5,
+      cooldownMs: 30_000,
+      now: () => new Date(nowMs),
+    });
+
+    // 0-2 errors remain healthy
+    await store.record(err("openai", "request_error", new Date(nowMs)));
+    await store.record(
+      err("openai", "request_error", new Date((nowMs += 10))),
+    );
+    let snap = await store.getProvider("openai");
+    expect(snap?.health).toBe("healthy");
+    expect(snap?.recentErrorCount).toBe(2);
+
+    // 3-4 => degraded
+    await store.record(
+      err("openai", "request_error", new Date((nowMs += 10))),
+    );
+    snap = await store.getProvider("openai");
+    expect(snap?.health).toBe("degraded");
+
+    await store.record(
+      err("openai", "request_error", new Date((nowMs += 10))),
+    );
+    snap = await store.getProvider("openai");
+    expect(snap?.health).toBe("degraded");
+    expect(snap?.recentErrorCount).toBe(4);
+
+    // 5 => dead + cooldown
+    await store.record(
+      err("openai", "timeout", new Date((nowMs += 10))),
+    );
+    snap = await store.getProvider("openai");
+    expect(snap?.health).toBe("dead");
+    expect(snap?.cooldownUntil).toBeGreaterThan(nowMs);
+    expect(snap?.healthReason).toMatch(/Error budget exhausted|Cooldown/);
+
+    // Still dead during cooldown even if window would eventually age out
+    nowMs += 5_000;
+    snap = await store.getProvider("openai");
+    expect(snap?.health).toBe("dead");
+
+    // After cooldown, and with aged-out errors, recovers to healthy
+    nowMs += 40_000;
+    snap = await store.getProvider("openai");
+    expect(snap?.health).toBe("healthy");
+    expect(snap?.cooldownUntil).toBeUndefined();
+  });
+
+  it("marks hard auth failure as dead immediately with cooldown", async () => {
+    const t0 = Date.UTC(2026, 0, 2, 0, 0, 0);
+    let nowMs = t0;
+    const store = new InMemoryUsageStore({
+      cooldownMs: 15_000,
+      now: () => new Date(nowMs),
+    });
+
+    const result = await store.record({
+      providerId: "gemini",
+      authTier: "subscription",
+      kind: "auth_failure",
+      at: new Date(nowMs),
+    });
+    expect(result.snapshot.health).toBe("dead");
+    expect(result.healthChanged).toBe(true);
+    expect(result.previousHealth).toBe("healthy");
+
+    nowMs += 20_000;
+    const snap = await store.getProvider("gemini");
+    // No recent window errors beyond the single err once pruned? still within window.
+    // Cooldown expired; single error is within healthy budget (default 2).
+    expect(snap?.health).toBe("healthy");
+  });
+
+  it("records subscription quota exhaustion separately from API-key spend", async () => {
+    const store = new InMemoryUsageStore();
+
+    await store.setSubscriptionQuota("claude", {
+      limit: 10,
+      used: 9,
+      status: "active",
+    });
+
+    // One more subscription unit exhausts.
+    await store.record({
+      providerId: "claude",
+      authTier: "subscription",
+      kind: "subscription_usage",
+      amount: 1,
+    });
+
+    let snap = await store.getProvider("claude");
+    expect(snap?.subscriptionStatus).toBe("exhausted");
+    expect(snap?.subscriptionQuotaRemaining).toBe(0);
+    expect(snap?.apiKeySpendUsd).toBe(0);
+    // Exhaustion alone is degraded, not necessarily dead.
+    expect(snap?.health).toBe("degraded");
+
+    // Paid fallback spend is tracked independently.
+    await store.record({
+      providerId: "claude",
+      authTier: "api-key",
+      kind: "api_key_spend",
+      amount: 0.03,
+    });
+    await store.record({
+      providerId: "claude",
+      authTier: "api-key",
+      kind: "api_key_spend",
+      amount: 0.02,
+    });
+
+    snap = await store.getProvider("claude");
+    expect(snap?.apiKeySpendUsd).toBeCloseTo(0.05, 8);
+    // Subscription counters unchanged by api-key spend.
+    expect(snap?.subscriptionQuotaUsed).toBe(10);
+    expect(snap?.subscriptionStatus).toBe("exhausted");
+  });
+
+  it("explains why paid fallback was or was not used", async () => {
+    const store = new InMemoryUsageStore();
+
+    // Healthy subscription with remaining quota => prefer subscription.
+    await store.setSubscriptionQuota("claude", {
+      limit: 100,
+      used: 10,
+      status: "active",
+    });
+    let explain = await store.explainPaidFallback("claude", {
+      hasApiKeyCandidate: true,
+    });
+    expect(explain.recommendation).toBe("prefer_subscription");
+    expect(explain.subscriptionQuotaRemaining).toBe(90);
+    expect(explain.usedPaidFallback).toBe(false);
+    expect(explain.reason).toMatch(/should not be used yet|preferred/i);
+
+    // Exhaust subscription => allow API-key fallback.
+    await store.setSubscriptionQuota("claude", {
+      limit: 100,
+      used: 100,
+      status: "exhausted",
+    });
+    explain = await store.explainPaidFallback("claude", {
+      hasApiKeyCandidate: true,
+    });
+    expect(explain.recommendation).toBe("allow_api_key_fallback");
+    expect(explain.reason).toMatch(/exhausted/i);
+
+    // After paid spend, explanation notes fallback was used.
+    await store.record({
+      providerId: "claude",
+      authTier: "api-key",
+      kind: "api_key_spend",
+      amount: 1.25,
+    });
+    explain = await store.explainPaidFallback("claude", {
+      hasApiKeyCandidate: true,
+    });
+    expect(explain.apiKeySpendUsd).toBe(1.25);
+    expect(explain.usedPaidFallback).toBe(true);
+    expect(explain.subscriptionQuotaRemaining).toBe(0);
+
+    // Distinguishes unknown / no subscription data + api-key only.
+    explain = await store.explainPaidFallback("unknown-provider", {
+      hasApiKeyCandidate: true,
+    });
+    expect(explain.recommendation).toBe("api_key_only");
+  });
+
+  it("toJSON never includes secrets or raw prompts", async () => {
+    const store = new InMemoryUsageStore();
+    await store.record({
+      providerId: "openai",
+      authTier: "api-key",
+      kind: "api_key_spend",
+      amount: 0.5,
+      detail: "sk-should-not-appear-in-json-anyway-but-caller-redacts",
+    });
+    const json = JSON.stringify(store.toJSON());
+    expect(json).not.toMatch(/sk-/);
+    expect(store.toJSON()).toMatchObject({
+      kind: "in-memory-usage",
+      providers: {
+        openai: {
+          apiKeySpendUsd: 0.5,
+        },
+      },
+    });
+  });
+});
+
+describe("InMemoryStateStore", () => {
+  it("composes audit + usage under one StateStore-style handle", async () => {
+    const state = new InMemoryStateStore();
+    await state.usage.setSubscriptionQuota("claude", {
+      limit: 5,
+      used: 5,
+      status: "exhausted",
+    });
+    const explain = await state.usage.explainPaidFallback("claude", {
+      hasApiKeyCandidate: true,
+    });
+    expect(explain.recommendation).toBe("allow_api_key_fallback");
+
+    const json = state.toJSON();
+    expect(json).toMatchObject({ kind: "in-memory-state" });
+    expect(JSON.stringify(json)).not.toMatch(/sk-/);
+  });
+});