zevairouter 1.0.13 → 1.0.14

package/cli/app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zevairouter",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "ZevaiRouter - AI Router with provider automation, multi-account workflows, and quota tracking",
   "bin": {
     "zevai": "./cli/cli.js"

package/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zevairouter-cli",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "ZevaiRouter CLI - Start and manage ZevaiRouter server",
   "bin": {
     "zevai": "./cli.js"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zevairouter",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "ZevaiRouter - AI Router with provider automation, multi-account workflows, and quota tracking",
   "bin": {
     "zevai": "./cli/cli.js"

package/src/app/(dashboard)/dashboard/profile/page.js

@@ -946,6 +946,21 @@ export default function ProfilePage() {
               </div>
             )}
 
+            {/* Most Quota (smart routing) */}
+            <div className="flex items-start sm:items-center justify-between gap-4 pt-4 border-t border-border/50">
+              <div className="flex-1 min-w-0">
+                <p className="font-medium text-sm sm:text-base">Most Quota</p>
+                <p className="text-xs sm:text-sm text-text-muted">
+                  Pick the account with the most remaining quota (uses cached usage)
+                </p>
+              </div>
+              <Toggle
+                checked={settings.fallbackStrategy === "most-quota"}
+                onChange={() => updateFallbackStrategy(settings.fallbackStrategy === "most-quota" ? "fill-first" : "most-quota")}
+                disabled={loading}
+              />
+            </div>
+
             {/* Combo Round Robin */}
             <div className="flex items-start sm:items-center justify-between gap-4 pt-4 border-t border-border/50">
               <div className="flex-1 min-w-0">

package/src/app/(dashboard)/dashboard/usage/components/ProviderLimits/index.js

@@ -403,7 +403,7 @@ export default function ProviderLimits() {
   );
 
   // Fetch quota for a specific connection
-  const fetchQuota = useCallback(async (connectionId, provider) => {
+  const fetchQuota = useCallback(async (connectionId, provider, force = false) => {
     setLoading((prev) => ({ ...prev, [connectionId]: true }));
     setErrors((prev) => ({ ...prev, [connectionId]: null }));
 
@@ -411,7 +411,7 @@ export default function ProviderLimits() {
       console.log(
         `[ProviderLimits] Fetching quota for ${provider} (${connectionId})`,
       );
-      const response = await fetch(`/api/usage/${connectionId}`);
+      const response = await fetch(`/api/usage/${connectionId}${force ? "?refresh=1" : ""}`);
 
       if (!response.ok) {
         const errorData = await response.json().catch(() => ({}));
@@ -636,7 +636,7 @@ export default function ProviderLimits() {
       );
 
       await Promise.all(
-        visibleConnections.map((conn) => fetchQuota(conn.id, conn.provider)),
+        visibleConnections.map((conn) => fetchQuota(conn.id, conn.provider, true)),
       );
 
       setLastUpdated(new Date());

package/src/app/api/init/route.js

@@ -1,4 +1,12 @@
 // This API route is called automatically to initialize app
+import { startQuotaRefreshLoop } from "@/lib/usage/quotaRefresh";
+
 export async function GET() {
+  // Start the background quota-refresh loop (guarded so it only starts once).
+  try {
+    startQuotaRefreshLoop();
+  } catch (e) {
+    console.warn(`[Init] quota refresh loop start failed: ${e.message}`);
+  }
   return new Response("Initialized", { status: 200 });
 }

package/src/app/api/usage/[connectionId]/route.js

@@ -1,188 +1,40 @@
 // Ensure proxyFetch is loaded to patch globalThis.fetch
 import "open-sse/index.js";
 
-import { getProviderConnectionById, updateProviderConnection } from "@/lib/localDb";
-import { getUsageForProvider } from "open-sse/services/usage.js";
-import { getExecutor } from "open-sse/executors/index.js";
-import { resolveConnectionProxyConfig } from "@/lib/network/connectionProxy";
-import { USAGE_APIKEY_PROVIDERS } from "@/shared/constants/providers";
+import { getQuotaSnapshot } from "@/lib/localDb";
+import { resolveUsageForConnection } from "@/lib/usage/quotaService";
 
-// Detect auth-expired messages returned by usage providers instead of throwing
-const AUTH_EXPIRED_PATTERNS = ["expired", "authentication", "unauthorized", "401", "re-authorize"];
-function isAuthExpiredMessage(usage) {
-  if (!usage?.message) return false;
-  const msg = usage.message.toLowerCase();
-  return AUTH_EXPIRED_PATTERNS.some((p) => msg.includes(p));
-}
-
-/**
- * Refresh credentials using executor and update database
- * @param {boolean} force - Skip needsRefresh check and always attempt refresh
- * @returns Promise<{ connection, refreshed: boolean }>
- */
-async function refreshAndUpdateCredentials(connection, force = false, proxyOptions = null) {
-  const executor = getExecutor(connection.provider);
-
-  // Build credentials object from connection
-  const credentials = {
-    accessToken: connection.accessToken,
-    refreshToken: connection.refreshToken,
-    idToken: connection.idToken,
-    expiresAt: connection.expiresAt || connection.tokenExpiresAt,
-    lastRefreshAt: connection.lastRefreshAt,
-    connectionId: connection.id,
-    providerSpecificData: connection.providerSpecificData,
-    // For GitHub
-    copilotToken: connection.providerSpecificData?.copilotToken,
-    copilotTokenExpiresAt: connection.providerSpecificData?.copilotTokenExpiresAt,
-  };
-
-  // Check if refresh is needed (skip when force=true)
-  const needsRefresh = force || executor.needsRefresh(credentials);
-
-  if (!needsRefresh) {
-    return { connection, refreshed: false };
-  }
-
-  // Use executor's refreshCredentials method (with optional proxy)
-  const refreshResult = await executor.refreshCredentials(credentials, console, proxyOptions);
-
-  if (!refreshResult) {
-    // Refresh failed but we still have an accessToken — try with existing token
-    if (connection.accessToken) {
-      return { connection, refreshed: false };
-    }
-    throw new Error("Failed to refresh credentials. Please re-authorize the connection.");
-  }
-
-  // Build update object
-  const now = new Date().toISOString();
-  const updateData = {
-    updatedAt: now,
-  };
-
-  // Update accessToken if present
-  if (refreshResult.accessToken) {
-    updateData.accessToken = refreshResult.accessToken;
-  }
-
-  // Update refreshToken if present
-  if (refreshResult.refreshToken) {
-    updateData.refreshToken = refreshResult.refreshToken;
-  }
-
-  if (refreshResult.idToken) {
-    updateData.idToken = refreshResult.idToken;
-  }
-
-  if (refreshResult.lastRefreshAt) {
-    updateData.lastRefreshAt = refreshResult.lastRefreshAt;
-  }
-
-  // Update token expiry
-  if (refreshResult.expiresIn) {
-    updateData.expiresAt = new Date(Date.now() + refreshResult.expiresIn * 1000).toISOString();
-    updateData.expiresIn = refreshResult.expiresIn;
-  } else if (refreshResult.expiresAt) {
-    updateData.expiresAt = refreshResult.expiresAt;
-  }
-
-  // Handle provider-specific data (copilotToken for GitHub, etc.)
-  const providerSpecificUpdates = {
-    ...(refreshResult.providerSpecificData || {}),
-    ...(refreshResult.copilotToken ? { copilotToken: refreshResult.copilotToken } : {}),
-    ...(refreshResult.copilotTokenExpiresAt ? { copilotTokenExpiresAt: refreshResult.copilotTokenExpiresAt } : {}),
-  };
-  if (Object.keys(providerSpecificUpdates).length > 0) {
-    updateData.providerSpecificData = {
-      ...(connection.providerSpecificData || {}),
-      ...providerSpecificUpdates,
-    };
-  }
-
-  // Update database
-  await updateProviderConnection(connection.id, updateData);
-
-  // Return updated connection
-  const updatedConnection = {
-    ...connection,
-    ...updateData,
-    providerSpecificData: updateData.providerSpecificData || connection.providerSpecificData,
-  };
-
-  return {
-    connection: updatedConnection,
-    refreshed: true,
-  };
-}
+// Serve cached quota when it's fresher than this; otherwise fetch live.
+const CACHE_FRESH_MS = 60 * 1000;
 
 /**
- * GET /api/usage/[connectionId] - Get usage data for a specific connection
+ * GET /api/usage/[connectionId] - Get usage data for a specific connection.
+ *
+ * Reads the server-side quota cache first (instant); only hits the upstream API
+ * when the cache is stale or `?refresh=1` is passed. Live fetches also write the
+ * cache so routing + dashboard stay in sync.
  */
 export async function GET(request, { params }) {
-  let connection;
+  let connectionId;
   try {
-    const { connectionId } = await params;
-
-
-    // Get connection from database
-    connection = await getProviderConnectionById(connectionId);
-    if (!connection) {
-      return Response.json({ error: "Connection not found" }, { status: 404 });
-    }
-
-    // Allow OAuth connections, plus whitelisted apikey providers (glm/minimax/...)
-    const isOAuth = connection.authType === "oauth";
-    const isApikeyEligible =
-      connection.authType === "apikey" &&
-      USAGE_APIKEY_PROVIDERS.includes(connection.provider);
-
-    if (!isOAuth && !isApikeyEligible) {
-      return Response.json({ message: "Usage not available for this connection" });
-    }
-
-    // Resolve connection proxy config; force strictProxy=false so quota/refresh fall back to direct on failure
-    const proxyConfig = await resolveConnectionProxyConfig(connection.providerSpecificData);
-    const proxyOptions = {
-      connectionProxyEnabled: proxyConfig.connectionProxyEnabled === true,
-      connectionProxyUrl: proxyConfig.connectionProxyUrl || "",
-      connectionNoProxy: proxyConfig.connectionNoProxy || "",
-      vercelRelayUrl: proxyConfig.vercelRelayUrl || "",
-      strictProxy: false,
-    };
-
-    // Refresh credentials only for OAuth connections (apikey has no token refresh)
-    if (isOAuth) {
-      try {
-        const result = await refreshAndUpdateCredentials(connection, false, proxyOptions);
-        connection = result.connection;
-      } catch (refreshError) {
-        console.error("[Usage API] Credential refresh failed:", refreshError);
-        return Response.json({
-          error: `Credential refresh failed: ${refreshError.message}`
-        }, { status: 401 });
+    ({ connectionId } = await params);
+    const url = new URL(request.url);
+    const force = url.searchParams.get("refresh") === "1";
+
+    if (!force) {
+      const snap = await getQuotaSnapshot(connectionId);
+      if (snap?.usage && Date.now() - new Date(snap.fetchedAt).getTime() < CACHE_FRESH_MS) {
+        return Response.json({ ...snap.usage, cached: true, fetchedAt: snap.fetchedAt });
       }
     }
 
-    // Fetch usage from provider API
-    let usage = await getUsageForProvider(connection, proxyOptions);
-
-    // If provider returned an auth-expired message instead of throwing,
-    // force-refresh token and retry once (OAuth only)
-    if (isOAuth && isAuthExpiredMessage(usage) && connection.refreshToken) {
-      try {
-        const retryResult = await refreshAndUpdateCredentials(connection, true, proxyOptions);
-        connection = retryResult.connection;
-        usage = await getUsageForProvider(connection, proxyOptions);
-      } catch (retryError) {
-        console.warn(`[Usage] ${connection.provider}: force refresh failed: ${retryError.message}`);
-      }
+    const usage = await resolveUsageForConnection(connectionId, { writeCache: true, force });
+    if (usage?.notFound) {
+      return Response.json({ error: "Connection not found" }, { status: 404 });
     }
-
     return Response.json(usage);
   } catch (error) {
-    const provider = connection?.provider ?? "unknown";
-    console.warn(`[Usage] ${provider}: ${error.message}`);
+    console.warn(`[Usage] ${connectionId || "unknown"}: ${error.message}`);
     return Response.json({ error: error.message }, { status: 500 });
   }
 }

package/src/app/globals.css

@@ -510,11 +510,9 @@ button {
     0 1px 2px rgba(15, 23, 42, 0.05),
     0 10px 24px -10px rgba(15, 23, 42, 0.18),
     0 24px 48px -24px rgba(15, 23, 42, 0.22);
-  transform: perspective(1200px) translateZ(0);
-  transform-style: preserve-3d;
-  transition: transform 0.35s cubic-bezier(0.22, 1, 0.36, 1),
+  transform: translateY(0);
+  transition: transform 0.3s cubic-bezier(0.22, 1, 0.36, 1),
               box-shadow 0.35s cubic-bezier(0.22, 1, 0.36, 1);
-  will-change: transform;
 }
 .card-3d::before {
   content: "";
@@ -527,7 +525,7 @@ button {
 }
 .card-3d > * { position: relative; z-index: 1; }
 .card-3d:hover {
-  transform: perspective(1200px) translateY(-3px) rotateX(1deg) rotateY(-1deg);
+  transform: translateY(-3px);
   box-shadow:
     inset 0 1px 0 0 rgba(255, 255, 255, 0.6),
     0 2px 4px rgba(15, 23, 42, 0.06),
@@ -568,8 +566,8 @@ button {
     0 44px 80px -28px rgba(0, 0, 0, 0.72);
 }
 
-/* Respect reduced-motion: keep depth, drop the tilt/scale animation */
+/* Respect reduced-motion: keep depth, drop the movement */
 @media (prefers-reduced-motion: reduce) {
   .card-3d { transition: box-shadow 0.3s ease; }
-  .card-3d:hover { transform: perspective(1200px) translateY(-2px); }
+  .card-3d:hover { transform: none; }
 }

package/src/lib/db/index.js

@@ -27,6 +27,12 @@ export {
   createProxyPool, updateProxyPool, deleteProxyPool,
 } from "./repos/proxyPoolsRepo.js";
 
+// Quota cache (server-side per-account quota snapshots for routing)
+export {
+  saveQuotaSnapshot, getQuotaSnapshot, getAllQuotaSnapshots,
+  deleteQuotaSnapshot, getCachedRemainingPercent,
+} from "./repos/quotaCacheRepo.js";
+
 // API keys
 export {
   getApiKeys, getApiKeyById, createApiKey, updateApiKey, deleteApiKey, validateApiKey,

package/src/lib/db/repos/quotaCacheRepo.js

@@ -0,0 +1,80 @@
+import { getAdapter } from "../driver.js";
+import { parseJson, stringifyJson } from "../helpers/jsonCol.js";
+
+/**
+ * Quota cache repo — server-side snapshots of upstream per-account quota.
+ *
+ * A background loop (see open-sse/services/quotaRefresh.js) periodically calls
+ * getUsageForProvider() and writes the result here so request routing can read
+ * remaining quota synchronously (one SQLite lookup) instead of a live network
+ * call. One row per connection.
+ */
+
+/**
+ * Upsert a quota snapshot for a connection.
+ * @param {string} connectionId
+ * @param {string} provider
+ * @param {object} usage - the object returned by getUsageForProvider (quotas, plan, message, accountDead...)
+ */
+export async function saveQuotaSnapshot(connectionId, provider, usage) {
+  if (!connectionId) return;
+  const db = await getAdapter();
+  const fetchedAt = new Date().toISOString();
+  db.run(
+    `INSERT INTO quotaCache(connectionId, provider, data, fetchedAt) VALUES(?, ?, ?, ?)
+     ON CONFLICT(connectionId) DO UPDATE SET provider = excluded.provider, data = excluded.data, fetchedAt = excluded.fetchedAt`,
+    [connectionId, provider || "", stringifyJson(usage || {}), fetchedAt]
+  );
+}
+
+function rowToSnapshot(row) {
+  if (!row) return null;
+  return {
+    connectionId: row.connectionId,
+    provider: row.provider,
+    fetchedAt: row.fetchedAt,
+    usage: parseJson(row.data, {}),
+  };
+}
+
+/** Get one connection's cached snapshot, or null. */
+export async function getQuotaSnapshot(connectionId) {
+  if (!connectionId) return null;
+  const db = await getAdapter();
+  const row = db.get(
+    `SELECT connectionId, provider, data, fetchedAt FROM quotaCache WHERE connectionId = ?`,
+    [connectionId]
+  );
+  return rowToSnapshot(row);
+}
+
+/** Get all cached snapshots (optionally filtered by provider). */
+export async function getAllQuotaSnapshots(provider = null) {
+  const db = await getAdapter();
+  const rows = provider
+    ? db.all(`SELECT connectionId, provider, data, fetchedAt FROM quotaCache WHERE provider = ?`, [provider])
+    : db.all(`SELECT connectionId, provider, data, fetchedAt FROM quotaCache`);
+  return rows.map(rowToSnapshot);
+}
+
+/** Delete a connection's snapshot (e.g. when the connection is removed). */
+export async function deleteQuotaSnapshot(connectionId) {
+  if (!connectionId) return;
+  const db = await getAdapter();
+  db.run(`DELETE FROM quotaCache WHERE connectionId = ?`, [connectionId]);
+}
+
+/**
+ * Read the best remaining-quota percentage for a connection+model from cache.
+ * Returns a number 0..100, or null when unknown (no snapshot / model absent).
+ * Used by the router's "most-quota" strategy.
+ */
+export async function getCachedRemainingPercent(connectionId, model) {
+  const snap = await getQuotaSnapshot(connectionId);
+  if (!snap) return null;
+  const quotas = snap.usage?.quotas;
+  if (!quotas || typeof quotas !== "object") return null;
+  const q = quotas[model];
+  if (!q || typeof q.remainingPercentage !== "number") return null;
+  return q.remainingPercentage;
+}

package/src/lib/db/schema.js

@@ -148,6 +148,21 @@ export const TABLES = {
       "CREATE INDEX IF NOT EXISTS idx_rd_conn ON requestDetails(connectionId)",
     ],
   },
+  // Server-side snapshot of upstream per-account quota, refreshed by a
+  // background loop. Lets routing read remaining quota synchronously without a
+  // live network call. One row per connection; `data` holds the quotas map +
+  // plan/message from getUsageForProvider.
+  quotaCache: {
+    columns: {
+      connectionId: "TEXT PRIMARY KEY",
+      provider: "TEXT",
+      data: "TEXT NOT NULL",
+      fetchedAt: "TEXT NOT NULL",
+    },
+    indexes: [
+      "CREATE INDEX IF NOT EXISTS idx_qc_provider ON quotaCache(provider)",
+    ],
+  },
 };
 
 export function buildCreateTableSql(name, def) {

package/src/lib/localDb.js

@@ -10,6 +10,8 @@ export {
   createProviderNode, updateProviderNode, deleteProviderNode,
   getProxyPools, getProxyPoolById,
   createProxyPool, updateProxyPool, deleteProxyPool,
+  saveQuotaSnapshot, getQuotaSnapshot, getAllQuotaSnapshots,
+  deleteQuotaSnapshot, getCachedRemainingPercent,
   getApiKeys, getApiKeyById, createApiKey, updateApiKey, deleteApiKey, validateApiKey,
   getCombos, getComboById, getComboByName,
   createCombo, updateCombo, deleteCombo,

package/src/lib/usage/quotaRefresh.js

@@ -0,0 +1,61 @@
+// Background quota refresh loop.
+//
+// Periodically snapshots each active, usage-eligible connection's upstream quota
+// into the server-side quota cache (quotaCache table) so request routing can read
+// remaining quota synchronously. Requests are staggered to avoid a burst of
+// upstream calls. Guarded via globalThis so Next.js hot-reload / multiple imports
+// don't start duplicate loops.
+
+import { getProviderConnections } from "@/lib/localDb";
+import { resolveUsageForConnection, isUsageEligible } from "./quotaService.js";
+
+const REFRESH_INTERVAL_MS = 5 * 60 * 1000; // full sweep cadence per connection
+const STAGGER_MS = 4 * 1000;               // gap between connections in a sweep
+const MIN_START_DELAY_MS = 15 * 1000;      // let the server settle before first sweep
+
+if (!globalThis._quotaRefreshState) {
+  globalThis._quotaRefreshState = { started: false, timer: null, running: false };
+}
+const state = globalThis._quotaRefreshState;
+
+async function sweepOnce() {
+  if (state.running) return;
+  state.running = true;
+  try {
+    let connections = [];
+    try {
+      connections = await getProviderConnections({ isActive: true });
+    } catch (e) {
+      console.warn(`[QuotaRefresh] failed to list connections: ${e.message}`);
+      return;
+    }
+    const eligible = connections.filter(isUsageEligible);
+    for (const conn of eligible) {
+      try {
+        await resolveUsageForConnection(conn.id, { writeCache: true });
+      } catch (e) {
+        console.warn(`[QuotaRefresh] ${conn.provider}/${conn.id}: ${e.message}`);
+      }
+      // Stagger to avoid hammering upstreams all at once.
+      await new Promise((r) => setTimeout(r, STAGGER_MS));
+    }
+  } finally {
+    state.running = false;
+  }
+}
+
+/** Start the background loop once per process. Safe to call repeatedly. */
+export function startQuotaRefreshLoop() {
+  if (state.started) return;
+  state.started = true;
+  setTimeout(() => {
+    void sweepOnce();
+    state.timer = setInterval(() => void sweepOnce(), REFRESH_INTERVAL_MS);
+    if (state.timer.unref) state.timer.unref();
+  }, MIN_START_DELAY_MS);
+}
+
+/** Trigger an immediate one-off sweep (fire-and-forget). */
+export function refreshQuotaNow() {
+  void sweepOnce();
+}

package/src/lib/usage/quotaService.js

@@ -0,0 +1,146 @@
+// Shared quota service: refresh credentials, fetch upstream usage, and write a
+// server-side cache snapshot. Used by both the /api/usage route (live view) and
+// the background refresh loop (routing cache). Extracted so both paths share one
+// implementation of the refresh→fetch→cache flow.
+
+import "open-sse/index.js"; // ensure proxyFetch patches globalThis.fetch
+import { getProviderConnectionById, updateProviderConnection, saveQuotaSnapshot } from "@/lib/localDb";
+import { getUsageForProvider } from "open-sse/services/usage.js";
+import { getExecutor } from "open-sse/executors/index.js";
+import { resolveConnectionProxyConfig } from "@/lib/network/connectionProxy";
+import { USAGE_APIKEY_PROVIDERS } from "@/shared/constants/providers";
+
+const AUTH_EXPIRED_PATTERNS = ["expired", "authentication", "unauthorized", "401", "re-authorize"];
+function isAuthExpiredMessage(usage) {
+  if (!usage?.message) return false;
+  const msg = usage.message.toLowerCase();
+  return AUTH_EXPIRED_PATTERNS.some((p) => msg.includes(p));
+}
+
+/**
+ * Refresh credentials via the provider executor and persist any updated tokens.
+ * @returns {Promise<{connection, refreshed: boolean}>}
+ */
+export async function refreshAndUpdateCredentials(connection, force = false, proxyOptions = null) {
+  const executor = getExecutor(connection.provider);
+
+  const credentials = {
+    accessToken: connection.accessToken,
+    refreshToken: connection.refreshToken,
+    idToken: connection.idToken,
+    expiresAt: connection.expiresAt || connection.tokenExpiresAt,
+    lastRefreshAt: connection.lastRefreshAt,
+    connectionId: connection.id,
+    providerSpecificData: connection.providerSpecificData,
+    copilotToken: connection.providerSpecificData?.copilotToken,
+    copilotTokenExpiresAt: connection.providerSpecificData?.copilotTokenExpiresAt,
+  };
+
+  const needsRefresh = force || executor.needsRefresh(credentials);
+  if (!needsRefresh) return { connection, refreshed: false };
+
+  const refreshResult = await executor.refreshCredentials(credentials, console, proxyOptions);
+  if (!refreshResult) {
+    if (connection.accessToken) return { connection, refreshed: false };
+    throw new Error("Failed to refresh credentials. Please re-authorize the connection.");
+  }
+
+  const now = new Date().toISOString();
+  const updateData = { updatedAt: now };
+  if (refreshResult.accessToken) updateData.accessToken = refreshResult.accessToken;
+  if (refreshResult.refreshToken) updateData.refreshToken = refreshResult.refreshToken;
+  if (refreshResult.idToken) updateData.idToken = refreshResult.idToken;
+  if (refreshResult.lastRefreshAt) updateData.lastRefreshAt = refreshResult.lastRefreshAt;
+  if (refreshResult.expiresIn) {
+    updateData.expiresAt = new Date(Date.now() + refreshResult.expiresIn * 1000).toISOString();
+    updateData.expiresIn = refreshResult.expiresIn;
+  } else if (refreshResult.expiresAt) {
+    updateData.expiresAt = refreshResult.expiresAt;
+  }
+
+  const providerSpecificUpdates = {
+    ...(refreshResult.providerSpecificData || {}),
+    ...(refreshResult.copilotToken ? { copilotToken: refreshResult.copilotToken } : {}),
+    ...(refreshResult.copilotTokenExpiresAt ? { copilotTokenExpiresAt: refreshResult.copilotTokenExpiresAt } : {}),
+  };
+  if (Object.keys(providerSpecificUpdates).length > 0) {
+    updateData.providerSpecificData = {
+      ...(connection.providerSpecificData || {}),
+      ...providerSpecificUpdates,
+    };
+  }
+
+  await updateProviderConnection(connection.id, updateData);
+  const updatedConnection = {
+    ...connection,
+    ...updateData,
+    providerSpecificData: updateData.providerSpecificData || connection.providerSpecificData,
+  };
+  return { connection: updatedConnection, refreshed: true };
+}
+
+function isUsageEligible(connection) {
+  if (!connection) return false;
+  if (connection.authType === "oauth") return true;
+  return connection.authType === "apikey" && USAGE_APIKEY_PROVIDERS.includes(connection.provider);
+}
+
+/**
+ * Full usage flow for one connection: resolve proxy → refresh token (OAuth) →
+ * fetch upstream usage → retry once on auth-expired. Optionally write the result
+ * to the server-side quota cache. Returns the usage object (may contain
+ * {quotas}, {message}, {accountDead}). Does not throw for expected states.
+ *
+ * @param {string} connectionId
+ * @param {object} opts { writeCache?: boolean, force?: boolean }
+ */
+export async function resolveUsageForConnection(connectionId, opts = {}) {
+  const { writeCache = false, force = false } = opts;
+  const connection = await getProviderConnectionById(connectionId);
+  if (!connection) return { error: "Connection not found", notFound: true };
+
+  if (!isUsageEligible(connection)) {
+    return { message: "Usage not available for this connection" };
+  }
+
+  const proxyConfig = await resolveConnectionProxyConfig(connection.providerSpecificData);
+  const proxyOptions = {
+    connectionProxyEnabled: proxyConfig.connectionProxyEnabled === true,
+    connectionProxyUrl: proxyConfig.connectionProxyUrl || "",
+    connectionNoProxy: proxyConfig.connectionNoProxy || "",
+    vercelRelayUrl: proxyConfig.vercelRelayUrl || "",
+    strictProxy: false,
+  };
+
+  let conn = connection;
+  const isOAuth = conn.authType === "oauth";
+
+  if (isOAuth) {
+    const result = await refreshAndUpdateCredentials(conn, force, proxyOptions);
+    conn = result.connection;
+  }
+
+  let usage = await getUsageForProvider(conn, proxyOptions);
+
+  if (isOAuth && isAuthExpiredMessage(usage) && conn.refreshToken) {
+    try {
+      const retry = await refreshAndUpdateCredentials(conn, true, proxyOptions);
+      conn = retry.connection;
+      usage = await getUsageForProvider(conn, proxyOptions);
+    } catch (retryError) {
+      console.warn(`[Usage] ${conn.provider}: force refresh failed: ${retryError.message}`);
+    }
+  }
+
+  if (writeCache && usage && !usage.error) {
+    try {
+      await saveQuotaSnapshot(conn.id, conn.provider, usage);
+    } catch (e) {
+      console.warn(`[QuotaCache] save failed for ${conn.id}: ${e.message}`);
+    }
+  }
+
+  return usage;
+}
+
+export { isUsageEligible };