offrouter-core 0.1.0 → 0.2.0

package/src/usage.ts

@@ -118,6 +118,25 @@ export interface AccountUsageSnapshot {
   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;
 }
 
@@ -576,7 +595,7 @@ export class InMemoryUsageStore implements UsageStore {
       if (input.used !== undefined) state.used = input.used;
       if (input.limit !== undefined) state.limit = input.limit;
       state.updatedAt = at.toISOString();
-      return toAccountSnapshot(state);
+      return computeAccountSnapshot(state);
     });
   }
 
@@ -589,7 +608,7 @@ export class InMemoryUsageStore implements UsageStore {
       const key = `${providerId}:${accountId}`;
       const state = this.#accounts.get(key);
       if (!state) return false;
-      return toAccountSnapshot(state, threshold).nearLimit;
+      return computeAccountSnapshot(state, threshold).nearLimit;
     });
   }
 
@@ -597,7 +616,7 @@ export class InMemoryUsageStore implements UsageStore {
     return this.#exclusive(() => {
       const out: AccountUsageSnapshot[] = [];
       for (const state of this.#accounts.values()) {
-        const snap = toAccountSnapshot(state, threshold);
+        const snap = computeAccountSnapshot(state, threshold);
         if (snap.nearLimit) out.push(snap);
       }
       return out.sort((a, b) => {
@@ -615,7 +634,7 @@ export class InMemoryUsageStore implements UsageStore {
       const key = `${providerId}:${accountId}`;
       const state = this.#accounts.get(key);
       if (!state) return undefined;
-      return toAccountSnapshot(state);
+      return computeAccountSnapshot(state);
     });
   }
 
@@ -623,7 +642,7 @@ export class InMemoryUsageStore implements UsageStore {
     return this.#exclusive(() => {
       const out: AccountUsageSnapshot[] = [];
       for (const state of this.#accounts.values()) {
-        out.push(toAccountSnapshot(state));
+        out.push(computeAccountSnapshot(state));
       }
       return out.sort((a, b) => {
         if (a.providerId !== b.providerId) return a.providerId.localeCompare(b.providerId);
@@ -763,38 +782,46 @@ function toSnapshot(state: InternalProviderState): ProviderUsageSnapshot {
   };
 }
 
-function toAccountSnapshot(
-  state: AccountQuotaState,
-  threshold?: number,
+export function computeAccountSnapshot(
+  doc: AccountUsageDoc,
+  threshold: number = DEFAULT_NEAR_LIMIT_THRESHOLD,
 ): AccountUsageSnapshot {
-  const t = threshold ?? DEFAULT_NEAR_LIMIT_THRESHOLD;
-  const limit = state.limit;
-  const used = state.used;
-  const remaining = limit === undefined ? undefined : Math.max(0, limit - used);
+  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";
-  } else if ((limit - used) / limit < t) {
+    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);
+    limit === undefined
+      ? undefined
+      : Math.round(((limit - used) / limit) * 100);
   return {
-    providerId: state.providerId,
-    accountId: state.accountId,
+    providerId: doc.providerId,
+    accountId: doc.accountId,
     used,
     limit,
     remaining,
     percentRemaining,
     nearLimit,
     subscriptionStatus: status,
-    updatedAt: state.updatedAt,
+    health,
+    updatedAt: doc.updatedAt,
   };
 }