@robhowley/pi-openrouter 0.9.0 → 0.9.1

package/extensions/openrouter/cache.ts

@@ -1,36 +1,38 @@
-import type { CacheEntry, UsageSummary, LocalUsageEvent, UsageAggregate } from './types.js';
+import type { CacheEntry, UsageSummary, LocalUsageEvent } from './types.js';
 import type { ActivityItem } from '@openrouter/sdk/models/index.js';
 import { aggregateUsage } from './format.js';
 import { getCredits, getActivity } from './client.js';
 import { readLocalUsage, aggregateLocal, getCurrentUtcDate, addUtcDays } from './local-usage.js';
-import { ZERO_AGGREGATE } from './types.js';
+import { combineUsageAggregates, createZeroAggregate } from './types.js';
 
 export const CACHE_TTL_MS = 45000;
 export const BACKGROUND_REFRESH_INTERVAL_MS = 30000;
 
+interface CacheGetOptions {
+  allowStale?: boolean;
+}
+
 export class TTLCache<T> {
   private cache = new Map<string, CacheEntry<T>>();
 
   constructor(private ttlMs: number = CACHE_TTL_MS) {}
 
-  get(key: string): T | undefined {
+  get(key: string, options: CacheGetOptions = {}): T | undefined {
     const entry = this.cache.get(key);
     if (!entry) return undefined;
 
-    if (Date.now() - entry.timestamp > this.ttlMs) {
-      this.cache.delete(key);
+    if (!options.allowStale && Date.now() - entry.timestamp > this.ttlMs) {
       return undefined;
     }
 
     return entry.data;
   }
 
-  getTimestamp(key: string): number | undefined {
+  getTimestamp(key: string, options: CacheGetOptions = {}): number | undefined {
     const entry = this.cache.get(key);
     if (!entry) return undefined;
 
-    if (Date.now() - entry.timestamp > this.ttlMs) {
-      this.cache.delete(key);
+    if (!options.allowStale && Date.now() - entry.timestamp > this.ttlMs) {
       return undefined;
     }
 
@@ -40,18 +42,175 @@ export class TTLCache<T> {
   set(key: string, data: T): void {
     this.cache.set(key, { data, timestamp: Date.now() });
   }
+
+  clear(key?: string): void {
+    if (key) {
+      this.cache.delete(key);
+      return;
+    }
+    this.cache.clear();
+  }
 }
 
 export const usageCache = new TTLCache<UsageSummary>(CACHE_TTL_MS);
 
-let refreshInterval: NodeJS.Timeout | null = null;
+export type RefreshStatus = 'idle' | 'healthy' | 'refreshing' | 'stale' | 'failed';
+
+export interface RefreshState {
+  status: RefreshStatus;
+  consecutiveFailures: number;
+  lastError: string | null;
+  lastSuccessAt: number | null;
+  nextDelayMs: number | null;
+}
+
+export interface StartBackgroundRefreshOptions {
+  onFailure?: (state: RefreshState) => void;
+}
+
+let refreshTimer: NodeJS.Timeout | null = null;
+let refreshActive = false;
 let consecutiveFailures = 0;
+let refreshFailureCallback: ((state: RefreshState) => void) | undefined;
+let refreshState: RefreshState = {
+  status: 'idle',
+  consecutiveFailures: 0,
+  lastError: null,
+  lastSuccessAt: null,
+  nextDelayMs: null,
+};
 const MAX_RETRY_BACKOFF = 5; // Max 2^5 = 32x base interval (16 min)
-const MAX_RETRY_COUNT = 4; // Stop after 4 consecutive failures
+const RATE_LIMIT_BACKOFF_MULTIPLIER = 8; // 4 minutes with the default 30s interval
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
 
-function getBackoffInterval(): number {
+export function isRateLimitError(error: unknown): boolean {
+  const message = getErrorMessage(error).toLowerCase();
+  return (
+    message.includes('429') || message.includes('rate limit') || message.includes('rate-limit')
+  );
+}
+
+function getBackoffInterval(error?: unknown): number {
   const backoffMultiplier = Math.min(consecutiveFailures, MAX_RETRY_BACKOFF);
-  return BACKGROUND_REFRESH_INTERVAL_MS * Math.pow(2, backoffMultiplier);
+  const exponentialDelay = BACKGROUND_REFRESH_INTERVAL_MS * Math.pow(2, backoffMultiplier);
+  const cappedDelay = Math.min(
+    exponentialDelay,
+    BACKGROUND_REFRESH_INTERVAL_MS * Math.pow(2, MAX_RETRY_BACKOFF),
+  );
+
+  if (!isRateLimitError(error)) {
+    return cappedDelay;
+  }
+
+  const rateLimitDelay = BACKGROUND_REFRESH_INTERVAL_MS * RATE_LIMIT_BACKOFF_MULTIPLIER;
+  return Math.min(
+    Math.max(cappedDelay, rateLimitDelay),
+    BACKGROUND_REFRESH_INTERVAL_MS * Math.pow(2, MAX_RETRY_BACKOFF),
+  );
+}
+
+export function getRefreshState(): RefreshState {
+  return { ...refreshState };
+}
+
+function scheduleRefresh(delay: number): void {
+  if (!refreshActive) return;
+  refreshState = { ...refreshState, nextDelayMs: delay };
+
+  refreshTimer = setTimeout(async () => {
+    refreshTimer = null;
+    await runBackgroundRefreshOnce();
+    if (refreshActive) {
+      scheduleRefresh(refreshState.nextDelayMs ?? BACKGROUND_REFRESH_INTERVAL_MS);
+    }
+  }, delay);
+}
+
+async function runBackgroundRefreshOnce(): Promise<void> {
+  refreshState = { ...refreshState, status: 'refreshing' };
+
+  try {
+    const summary = await fetchAndAggregate();
+    if (!summary) {
+      throw new Error('OpenRouter usage unavailable: no configured API key or credits response.');
+    }
+
+    usageCache.set('usage', summary);
+    consecutiveFailures = 0;
+    refreshState = {
+      status: 'healthy',
+      consecutiveFailures,
+      lastError: null,
+      lastSuccessAt: Date.now(),
+      nextDelayMs: BACKGROUND_REFRESH_INTERVAL_MS,
+    };
+  } catch (error) {
+    consecutiveFailures++;
+    const hasStaleData = usageCache.get('usage', { allowStale: true }) !== undefined;
+    refreshState = {
+      status: hasStaleData ? 'stale' : 'failed',
+      consecutiveFailures,
+      lastError: getErrorMessage(error),
+      lastSuccessAt: refreshState.lastSuccessAt,
+      nextDelayMs: getBackoffInterval(error),
+    };
+    refreshFailureCallback?.(getRefreshState());
+  }
+}
+
+/**
+ * Extract the latest date from Activity API data.
+ * Returns undefined if analytics is null, empty, or has no valid dates.
+ */
+function getOfficialThroughDate(analytics: ActivityItem[] | null): string | undefined {
+  if (!analytics || analytics.length === 0) return undefined;
+  let maxDate = '';
+  // Match YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
+  const dateRE = /^\d{4}-\d{2}-\d{2}/;
+  for (let i = 0; i < analytics.length; i++) {
+    const d = analytics[i];
+    if (d && d.date && dateRE.test(d.date)) {
+      const datePart = d.date.slice(0, 10); // Extract YYYY-MM-DD
+      if (datePart > maxDate) {
+        maxDate = datePart;
+      }
+    }
+  }
+  return maxDate || undefined;
+}
+
+/**
+ * Compute the date range for reading local JSONL usage.
+ * Returns { fromDateUtc, toDateUtc } for the bounded window.
+ *
+ * Product decision:
+ * - If officialThroughDate exists: read from day after through today,
+ *   but cap to 30-day window (never read more than today - 29 through today)
+ * - If no official data: read from today - 29 days through today (30 days total)
+ */
+function getLocalUsageReadRange(
+  officialThroughDate: string | undefined,
+  now: string,
+): { fromDateUtc: string; toDateUtc: string } {
+  const fallbackStart = addUtcDays(now, -29); // 30-day window start
+
+  if (officialThroughDate) {
+    const dayAfterOfficial = addUtcDays(officialThroughDate, 1);
+    // Cap to 30-day window: use the later of dayAfterOfficial or fallbackStart
+    return {
+      fromDateUtc: dayAfterOfficial > fallbackStart ? dayAfterOfficial : fallbackStart,
+      toDateUtc: now,
+    };
+  } else {
+    // No official data: read bounded 30-day window (today - 29 through today)
+    return {
+      fromDateUtc: fallbackStart,
+      toDateUtc: now,
+    };
+  }
 }
 
 export async function fetchAndAggregate(): Promise<UsageSummary | null> {
@@ -69,22 +228,7 @@ export async function fetchAndAggregate(): Promise<UsageSummary | null> {
   const timestamp = Date.now();
 
   // Get official aggregate from Activity API data
-  const officialThroughDate = (function (): string | undefined {
-    if (!analytics || analytics.length === 0) return undefined;
-    let maxDate = '';
-    // Match YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
-    const dateRE = /^\d{4}-\d{2}-\d{2}/;
-    for (let i = 0; i < analytics.length; i++) {
-      const d = analytics[i];
-      if (d && d.date && dateRE.test(d.date)) {
-        const datePart = d.date.slice(0, 10); // Extract YYYY-MM-DD
-        if (datePart > maxDate) {
-          maxDate = datePart;
-        }
-      }
-    }
-    return maxDate || undefined;
-  })();
+  const officialThroughDate = getOfficialThroughDate(analytics);
 
   // Compute official aggregate (only from Activity API data up to officialThroughDate)
   const officialAggregate =
@@ -106,38 +250,25 @@ export async function fetchAndAggregate(): Promise<UsageSummary | null> {
               }) as LocalUsageEvent,
           ),
         )
-      : ZERO_AGGREGATE;
+      : createZeroAggregate();
 
-  // Read local JSONL after officialThroughDate
+  // Read local JSONL for bounded recent window
+  // Always compute local read range when credits exist (Activity API may be absent/empty)
+  const now = getCurrentUtcDate();
+  const localReadRange = getLocalUsageReadRange(officialThroughDate, now);
   const localEvents: LocalUsageEvent[] = [];
-  if (officialThroughDate) {
-    // Read from the day after officialThroughDate to today
-    const localFrom = addUtcDays(officialThroughDate, 1);
-    const localTo = getCurrentUtcDate();
-    try {
-      const localEventsList = await readLocalUsage({
-        fromDateUtc: localFrom,
-        toDateUtc: localTo,
-      });
-      localEvents.push(...localEventsList);
-    } catch {
-      // Fail open - if local read fails, continue with empty local
-    }
+  try {
+    const localEventsList = await readLocalUsage(localReadRange);
+    localEvents.push(...localEventsList);
+  } catch {
+    // Fail open - if local read fails, continue with empty local
   }
 
   // Aggregate local events
   const localAggregate = aggregateLocal(localEvents);
 
   // Combine official + local
-  const combinedAggregate: UsageAggregate = {
-    requests: officialAggregate.requests + localAggregate.requests,
-    promptTokens: officialAggregate.promptTokens + localAggregate.promptTokens,
-    completionTokens: officialAggregate.completionTokens + localAggregate.completionTokens,
-    reasoningTokens: officialAggregate.reasoningTokens + localAggregate.reasoningTokens,
-    cacheReadTokens: officialAggregate.cacheReadTokens + localAggregate.cacheReadTokens,
-    cacheWriteTokens: officialAggregate.cacheWriteTokens + localAggregate.cacheWriteTokens,
-    cost: officialAggregate.cost + localAggregate.cost,
-  };
+  const combinedAggregate = combineUsageAggregates(officialAggregate, localAggregate);
 
   // Build full summary with local events included for 7d/30d totals
   const summary = aggregateUsage(credits, analytics ?? [], timestamp, localEvents);
@@ -150,47 +281,28 @@ export async function fetchAndAggregate(): Promise<UsageSummary | null> {
   return summary;
 }
 
-function scheduleRefresh(): void {
-  const delay = consecutiveFailures > 0 ? getBackoffInterval() : BACKGROUND_REFRESH_INTERVAL_MS;
-
-  refreshInterval = setInterval(async () => {
-    try {
-      const summary = await fetchAndAggregate();
-      if (summary) {
-        usageCache.set('usage', summary);
-
-        // Reset failure count on success and restart with normal interval
-        if (consecutiveFailures > 0) {
-          consecutiveFailures = 0;
-          stopBackgroundRefresh();
-          scheduleRefresh();
-        }
-      }
-    } catch {
-      consecutiveFailures++;
-
-      // Stop after max retries reached
-      if (consecutiveFailures >= MAX_RETRY_COUNT) {
-        stopBackgroundRefresh();
-        // TODO: Fire UI notification for persistent failure
-        return;
-      }
-
-      // Restart with backoff interval
-      stopBackgroundRefresh();
-      scheduleRefresh();
-    }
-  }, delay);
-}
-
-export function startBackgroundRefresh(): void {
-  if (refreshInterval) return;
-  scheduleRefresh();
+export function startBackgroundRefresh(options: StartBackgroundRefreshOptions = {}): void {
+  if (options.onFailure) {
+    refreshFailureCallback = options.onFailure;
+  }
+  if (refreshActive || refreshTimer) return;
+  refreshActive = true;
+  scheduleRefresh(BACKGROUND_REFRESH_INTERVAL_MS);
 }
 
 export function stopBackgroundRefresh(): void {
-  if (refreshInterval) {
-    clearInterval(refreshInterval);
-    refreshInterval = null;
+  refreshActive = false;
+  refreshFailureCallback = undefined;
+  if (refreshTimer) {
+    clearTimeout(refreshTimer);
+    refreshTimer = null;
   }
+  consecutiveFailures = 0;
+  refreshState = {
+    status: 'idle',
+    consecutiveFailures,
+    lastError: null,
+    lastSuccessAt: null,
+    nextDelayMs: null,
+  };
 }

package/extensions/openrouter/client.ts

@@ -8,7 +8,7 @@ let client: OpenRouter | null = null;
 
 function getClient(): OpenRouter | null {
   if (client) return client;
-  const apiKey = process.env['OPENROUTER_MANAGEMENT_KEY'] || process.env['OPENROUTER_API_KEY'];
+  const apiKey = getUsageApiKey();
   if (!apiKey) return null;
   client = new OpenRouter({ apiKey });
   return client;
@@ -41,9 +41,11 @@ export async function getActivity(): Promise<ActivityResponse['data'] | null> {
  * Uses the SDK for consistent error handling and retry behavior.
  */
 export async function fetchUserModels(): Promise<ModelsListResponse> {
-  const key = getApiKey();
+  const key = getModelSyncApiKey();
   if (!key) {
-    throw new AuthError('OPENROUTER_API_KEY not set');
+    throw new AuthError(
+      'OpenRouter API key not configured. Set OPENROUTER_API_KEY or OPENROUTER_MANAGEMENT_KEY.',
+    );
   }
 
   try {
@@ -69,6 +71,50 @@ export function getApiKey(): string | undefined {
   return process.env['OPENROUTER_API_KEY'];
 }
 
+/**
+ * Get the API key for usage/account endpoints.
+ * Prefers OPENROUTER_MANAGEMENT_KEY for full analytics access.
+ */
+export function getUsageApiKey(): string | undefined {
+  const mgmtKey = process.env['OPENROUTER_MANAGEMENT_KEY'];
+  const apiKey = process.env['OPENROUTER_API_KEY'];
+  // Treat empty strings as absent
+  return mgmtKey && mgmtKey.trim() !== ''
+    ? mgmtKey
+    : apiKey && apiKey.trim() !== ''
+      ? apiKey
+      : undefined;
+}
+
+/**
+ * Get the API key for model sync endpoint.
+ * Prefers OPENROUTER_API_KEY but falls back to OPENROUTER_MANAGEMENT_KEY.
+ */
+export function getModelSyncApiKey(): string | undefined {
+  const apiKey = process.env['OPENROUTER_API_KEY'];
+  const mgmtKey = process.env['OPENROUTER_MANAGEMENT_KEY'];
+  // Treat empty strings as absent
+  return apiKey && apiKey.trim() !== ''
+    ? apiKey
+    : mgmtKey && mgmtKey.trim() !== ''
+      ? mgmtKey
+      : undefined;
+}
+
+/**
+ * Check if model sync is configured.
+ */
+export function isConfiguredForModelSync(): boolean {
+  return !!getModelSyncApiKey();
+}
+
+/**
+ * Check if usage/account endpoints are configured.
+ */
+export function isConfiguredForUsage(): boolean {
+  return !!getUsageApiKey();
+}
+
 /**
  * Map SDK errors to our error types with proper status codes.
  */