offrouter-core 0.0.0 → 0.2.0

package/src/usage.ts

@@ -104,6 +104,42 @@ export interface RecordUsageResult {
   previousHealth: ProviderHealth;
 }
 
+export const DEFAULT_NEAR_LIMIT_THRESHOLD = 0.2;
+
+/**
+ * Snapshot of usage for a specific account within a provider.
+ */
+export interface AccountUsageSnapshot {
+  providerId: string;
+  accountId: string;
+  used: number;
+  limit?: number;
+  remaining?: number;
+  percentRemaining?: number;
+  nearLimit: boolean;
+  subscriptionStatus: SubscriptionStatus;
+  /**
+   * Derived account health from quota usage: "dead" when exhausted,
+   * "degraded" when near-limit, otherwise "healthy". Useful for
+   * persisted stores that need a stable, restorable health signal.
+   */
+  health?: ProviderHealth;
+  updatedAt: string;
+}
+
+/**
+ * Minimal persisted document for a single account's quota usage.
+ * Shared between the in-memory and file-backed usage stores so snapshot
+ * math stays in one place.
+ */
+export interface AccountUsageDoc {
+  providerId: string;
+  accountId: string;
+  used: number;
+  limit?: number;
+  updatedAt: string;
+}
+
 /**
  * Why paid API-key capacity was or was not selected given current usage state.
  * Consumed by doctor / status / route explain surfaces.
@@ -154,6 +190,35 @@ export interface UsageStore {
     options?: { hasApiKeyCandidate?: boolean },
   ): Promise<PaidFallbackExplanation>;
 
+  /**
+   * Record usage for a specific account within a provider.
+   */
+  recordUsage(
+    providerId: string,
+    accountId: string,
+    input: { used?: number; limit?: number; at?: Date },
+  ): Promise<AccountUsageSnapshot>;
+
+  /**
+   * Check whether a specific account is near its quota limit.
+   */
+  isNearLimit(providerId: string, accountId: string, threshold?: number): Promise<boolean>;
+
+  /**
+   * Get all accounts whose usage is near their quota limit.
+   */
+  getNearLimitAccounts(threshold?: number): Promise<AccountUsageSnapshot[]>;
+
+  /**
+   * Get the usage snapshot for a specific account.
+   */
+  getAccountUsage(providerId: string, accountId: string): Promise<AccountUsageSnapshot | undefined>;
+
+  /**
+   * List all account usage snapshots.
+   */
+  listAccountUsage(): Promise<AccountUsageSnapshot[]>;
+
   /**
    * JSON-safe diagnostic view. No secrets.
    */
@@ -184,6 +249,14 @@ interface InternalProviderState {
   updatedAt: string;
 }
 
+interface AccountQuotaState {
+  providerId: string;
+  accountId: string;
+  used: number;
+  limit?: number;
+  updatedAt: string;
+}
+
 const DEFAULT_WINDOW_MS = 60_000;
 const DEFAULT_HEALTHY_MAX_ERRORS = 2;
 const DEFAULT_DEAD_MIN_ERRORS = 5;
@@ -200,6 +273,7 @@ const HARD_ERROR_KINDS: ReadonlySet<UsageEventKind> = new Set([
  */
 export class InMemoryUsageStore implements UsageStore {
   readonly #providers = new Map<string, InternalProviderState>();
+  readonly #accounts = new Map<string, AccountQuotaState>();
   readonly #windowMs: number;
   readonly #healthyMaxErrors: number;
   readonly #deadMinErrors: number;
@@ -505,6 +579,78 @@ export class InMemoryUsageStore implements UsageStore {
     };
   }
 
+  async recordUsage(
+    providerId: string,
+    accountId: string,
+    input: { used?: number; limit?: number; at?: Date },
+  ): Promise<AccountUsageSnapshot> {
+    return this.#exclusive(() => {
+      const at = input.at ?? this.#now();
+      const key = `${providerId}:${accountId}`;
+      let state = this.#accounts.get(key);
+      if (!state) {
+        state = { providerId, accountId, used: 0, updatedAt: at.toISOString() };
+        this.#accounts.set(key, state);
+      }
+      if (input.used !== undefined) state.used = input.used;
+      if (input.limit !== undefined) state.limit = input.limit;
+      state.updatedAt = at.toISOString();
+      return computeAccountSnapshot(state);
+    });
+  }
+
+  async isNearLimit(
+    providerId: string,
+    accountId: string,
+    threshold?: number,
+  ): Promise<boolean> {
+    return this.#exclusive(() => {
+      const key = `${providerId}:${accountId}`;
+      const state = this.#accounts.get(key);
+      if (!state) return false;
+      return computeAccountSnapshot(state, threshold).nearLimit;
+    });
+  }
+
+  async getNearLimitAccounts(threshold?: number): Promise<AccountUsageSnapshot[]> {
+    return this.#exclusive(() => {
+      const out: AccountUsageSnapshot[] = [];
+      for (const state of this.#accounts.values()) {
+        const snap = computeAccountSnapshot(state, threshold);
+        if (snap.nearLimit) out.push(snap);
+      }
+      return out.sort((a, b) => {
+        if (a.providerId !== b.providerId) return a.providerId.localeCompare(b.providerId);
+        return a.accountId.localeCompare(b.accountId);
+      });
+    });
+  }
+
+  async getAccountUsage(
+    providerId: string,
+    accountId: string,
+  ): Promise<AccountUsageSnapshot | undefined> {
+    return this.#exclusive(() => {
+      const key = `${providerId}:${accountId}`;
+      const state = this.#accounts.get(key);
+      if (!state) return undefined;
+      return computeAccountSnapshot(state);
+    });
+  }
+
+  async listAccountUsage(): Promise<AccountUsageSnapshot[]> {
+    return this.#exclusive(() => {
+      const out: AccountUsageSnapshot[] = [];
+      for (const state of this.#accounts.values()) {
+        out.push(computeAccountSnapshot(state));
+      }
+      return out.sort((a, b) => {
+        if (a.providerId !== b.providerId) return a.providerId.localeCompare(b.providerId);
+        return a.accountId.localeCompare(b.accountId);
+      });
+    });
+  }
+
   toJSON(): Record<string, unknown> {
     const providers: Record<string, unknown> = {};
     for (const [id, state] of this.#providers) {
@@ -523,6 +669,7 @@ export class InMemoryUsageStore implements UsageStore {
     return {
       kind: "in-memory-usage",
       providers,
+      accounts: Object.fromEntries(this.#accounts),
     };
   }
 
@@ -635,6 +782,49 @@ function toSnapshot(state: InternalProviderState): ProviderUsageSnapshot {
   };
 }
 
+export function computeAccountSnapshot(
+  doc: AccountUsageDoc,
+  threshold: number = DEFAULT_NEAR_LIMIT_THRESHOLD,
+): AccountUsageSnapshot {
+  const limit = doc.limit;
+  const used = doc.used;
+  const remaining =
+    limit === undefined ? undefined : Math.max(0, limit - used);
+  let status: SubscriptionStatus;
+  let nearLimit = false;
+  let health: ProviderHealth;
+  if (limit === undefined) {
+    status = "unknown";
+    health = "healthy";
+  } else if (used >= limit) {
+    status = "exhausted";
+    health = "dead";
+  } else if ((limit - used) / limit < threshold) {
+    status = "near-limit";
+    nearLimit = true;
+    health = "degraded";
+  } else {
+    status = "active";
+    health = "healthy";
+  }
+  const percentRemaining =
+    limit === undefined
+      ? undefined
+      : Math.round(((limit - used) / limit) * 100);
+  return {
+    providerId: doc.providerId,
+    accountId: doc.accountId,
+    used,
+    limit,
+    remaining,
+    percentRemaining,
+    nearLimit,
+    subscriptionStatus: status,
+    health,
+    updatedAt: doc.updatedAt,
+  };
+}
+
 /**
  * Composite facade for callers that want one injectable "state" handle.
  * Writes stay on the specialized stores; this is a thin convenience.