@robhowley/pi-openrouter 0.7.1 → 0.8.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-openrouter
 
-A [Pi](https://pi.dev/) extension for live OpenRouter visibility: TUI overlays for spend, credits, key limits, burn rate, and model usage, plus automatic `session_id` tagging for dashboard grouping.
+A [Pi](https://pi.dev/) extension for live OpenRouter visibility and environment sync: usage/account TUI overlays, automatic `session_id` tagging, and user-scoped model catalog sync.
 
 ## Installation
 
@@ -13,13 +13,53 @@ pi install npm:@robhowley/pi-openrouter
 Set one of these environment variables:
 
 - `OPENROUTER_MANAGEMENT_KEY` (preferred), provides full usage data including model breakdowns
-- `OPENROUTER_API_KEY`, basic usage data only
+- `OPENROUTER_API_KEY`, basic usage data plus user-scoped model sync
 
 ```shell
 export OPENROUTER_MANAGEMENT_KEY=sk-or-...
 ```
 
-## Usage
+## Commands
+
+```bash
+/openrouter usage                    # usage/spend overlay
+/openrouter account                  # credits, key limits, account health
+/openrouter session                  # current OpenRouter session_id
+/openrouter models-sync              # sync user-scoped OpenRouter models into Pi
+/openrouter models-status            # show model sync/cache status
+/openrouter models-status --skipped  # show skipped model reasons
+```
+
+## Model catalog sync
+
+`pi-openrouter` can sync Pi’s OpenRouter model catalog from your user-scoped OpenRouter model list.
+
+`/openrouter models-sync`
+
+The sync uses OpenRouter’s authenticated user model catalog, so Pi can see the models available to your account instead of only the default provider list.
+
+`/openrouter models-status`
+
+Example status output:
+
+```text
+OpenRouter models healthy
+363 registered · 2 skipped · cache age: 2m
+```
+
+To see why models were skipped:
+
+`/openrouter models-status --skipped`
+
+Skipped models do not make the sync fail; models are skipped when required metadata cannot be safely mapped into Pi’s provider model config. The last successful catalog is cached so Pi can keep using it if a later refresh fails, and the cache persists across sessions. If a session starts with a cached catalog that has not been registered yet, status will show:
+
+```text
+OpenRouter models cached
+368 models in cache · age: 4m
+Run '/openrouter models-sync' to register models
+```
+
+## Usage overlay
 
 Type `/openrouter usage` in Pi to open the usage overlay.
 

package/extensions/openrouter/__tests__/client.test.ts

@@ -0,0 +1,169 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { fetchUserModels, isConfigured, getApiKey, ApiError, AuthError } from '../client.js';
+import { restoreEnv } from './fixtures.js';
+import type { Mock } from 'vitest';
+
+// Mock SDK at the module level
+vi.mock('@openrouter/sdk/sdk/sdk.js', () => ({
+  OpenRouter: vi.fn(),
+}));
+
+/**
+ * Factory function to create a minimal mock SDK client.
+ * Reduces boilerplate from ~25 lines to 1 line per test.
+ */
+function createMockSDKClient(overrides: { listForUser?: Mock } = {}) {
+  return {
+    models: { listForUser: overrides.listForUser ?? vi.fn() },
+    credits: {},
+    analytics: {},
+    chat: {},
+    embeddings: {},
+    images: {},
+    fine_tuning: {},
+    batches: {},
+    files: {},
+    audio: {},
+    moderation: {},
+    beta: {},
+    webhooks: {},
+    fineTunes: {},
+    jobs: {},
+    uploads: {},
+    assistants: {},
+    threads: {},
+    runs: {},
+    messages: {},
+    vectorStores: {},
+    tools: {},
+  };
+}
+
+describe('fetchUserModels', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    restoreEnv();
+  });
+
+  it('should throw AuthError when API key not set', async () => {
+    delete process.env['OPENROUTER_API_KEY'];
+
+    await expect(fetchUserModels()).rejects.toThrow('OPENROUTER_API_KEY not set');
+    await expect(fetchUserModels()).rejects.toBeInstanceOf(AuthError);
+  });
+
+  it('should fetch models with SDK', async () => {
+    process.env['OPENROUTER_API_KEY'] = 'test-key';
+
+    const mockResponse = {
+      data: [
+        {
+          id: 'openai/gpt-4',
+          name: 'GPT-4',
+          context_length: 8192,
+          pricing: { prompt: '0.00003', completion: '0.00006' },
+        },
+      ],
+    };
+
+    // Mock SDK OpenRouter class
+    const MockOpenRouter = vi.mocked((await import('@openrouter/sdk/sdk/sdk.js')).OpenRouter);
+    const mockClient = createMockSDKClient({
+      listForUser: vi.fn().mockResolvedValue(mockResponse),
+    });
+    MockOpenRouter.mockImplementation(() => mockClient as any);
+
+    const result = await fetchUserModels();
+
+    expect(result!.data).toHaveLength(1);
+    expect(result!.data[0]!.id).toBe('openai/gpt-4');
+    expect(mockClient.models.listForUser).toHaveBeenCalled();
+  });
+
+  it('should throw ApiError on 401 unauthorized', async () => {
+    process.env['OPENROUTER_API_KEY'] = 'invalid-key';
+
+    const MockOpenRouter = vi.mocked((await import('@openrouter/sdk/sdk/sdk.js')).OpenRouter);
+    const mockClient = createMockSDKClient({
+      listForUser: vi.fn().mockRejectedValue(new Error('Unauthorized')),
+    });
+    MockOpenRouter.mockImplementation(() => mockClient as any);
+
+    const error = await fetchUserModels().catch((e) => e);
+    expect(error).toBeInstanceOf(ApiError);
+    expect(error.message).toContain('Unauthorized');
+    expect((error as ApiError).statusCode).toBe(401);
+  });
+
+  it('should throw ApiError on rate limit (429)', async () => {
+    process.env['OPENROUTER_API_KEY'] = 'test-key';
+
+    const MockOpenRouter = vi.mocked((await import('@openrouter/sdk/sdk/sdk.js')).OpenRouter);
+    const mockClient = createMockSDKClient({
+      listForUser: vi.fn().mockRejectedValue(new Error('Rate limited')),
+    });
+    MockOpenRouter.mockImplementation(() => mockClient as any);
+
+    const error = await fetchUserModels().catch((e) => e);
+    expect(error).toBeInstanceOf(ApiError);
+    expect(error.message).toContain('Rate limited');
+    expect((error as ApiError).statusCode).toBe(429);
+  });
+
+  it('should throw ApiError on server error', async () => {
+    process.env['OPENROUTER_API_KEY'] = 'test-key';
+
+    const MockOpenRouter = vi.mocked((await import('@openrouter/sdk/sdk/sdk.js')).OpenRouter);
+    const mockClient = createMockSDKClient({
+      listForUser: vi.fn().mockRejectedValue(new Error('Server error')),
+    });
+    MockOpenRouter.mockImplementation(() => mockClient as any);
+
+    const error = await fetchUserModels().catch((e) => e);
+    expect(error).toBeInstanceOf(ApiError);
+    expect(error.message).toContain('Server error');
+    expect((error as ApiError).statusCode).toBe(500);
+  });
+});
+
+describe('isConfigured', () => {
+  beforeEach(() => {
+    restoreEnv();
+  });
+
+  it('should return true when API key is set', () => {
+    process.env['OPENROUTER_API_KEY'] = 'test-key';
+    expect(isConfigured()).toBe(true);
+  });
+
+  it('should return false when API key is not set', () => {
+    delete process.env['OPENROUTER_API_KEY'];
+    expect(isConfigured()).toBe(false);
+  });
+
+  it('should return false when API key is empty string', () => {
+    process.env['OPENROUTER_API_KEY'] = '';
+    expect(isConfigured()).toBe(false);
+  });
+});
+
+describe('getApiKey', () => {
+  beforeEach(() => {
+    restoreEnv();
+  });
+
+  it('should return the API key when set', () => {
+    process.env['OPENROUTER_API_KEY'] = 'test-key';
+    expect(getApiKey()).toBe('test-key');
+  });
+
+  it('should return undefined when API key is not set', () => {
+    delete process.env['OPENROUTER_API_KEY'];
+    expect(getApiKey()).toBeUndefined();
+  });
+
+  it('should return empty string when API key is empty', () => {
+    process.env['OPENROUTER_API_KEY'] = '';
+    expect(getApiKey()).toBe('');
+  });
+});

package/extensions/openrouter/__tests__/fixtures.ts

@@ -0,0 +1,134 @@
+/**
+ * Shared test fixtures for OpenRouter extension tests.
+ *
+ * Centralizes common test data shapes to reduce duplication across test files.
+ * Import: import { createValidModel, createActivityItem, ... } from './fixtures.js'
+ */
+
+import type { OpenRouterModel, ModelsCache, PiModelConfig } from '../models/types.js';
+import type { ActivityItem } from '@openrouter/sdk/models/index.js';
+
+// =============================================================================
+// Environment Helpers
+// =============================================================================
+
+/**
+ * Snapshot of process.env captured at module load time.
+ * Used as the baseline for restoreEnv() in tests.
+ */
+const originalEnvSnapshot: Record<string, string | undefined> = { ...process.env };
+
+/**
+ * Restore process.env to its original state.
+ * Call in beforeEach or afterEach to ensure clean environment between tests.
+ */
+export function restoreEnv(): void {
+  process.env = { ...originalEnvSnapshot };
+}
+
+/**
+ * Clear a specific environment variable.
+ */
+export function clearEnv(key: string): void {
+  delete process.env[key];
+}
+
+/**
+ * Set an environment variable for testing.
+ */
+export function setEnv(key: string, value: string): void {
+  process.env[key] = value;
+}
+
+// =============================================================================
+// Model Fixtures
+// =============================================================================
+
+/**
+ * Creates a valid OpenRouterModel with sensible defaults.
+ * Use overrides to customize specific properties for test cases.
+ */
+export function createValidModel(overrides?: Partial<OpenRouterModel>): OpenRouterModel {
+  return {
+    id: 'test/model',
+    name: 'Test Model',
+    context_length: 128000,
+    pricing: {
+      prompt: '0.0000005',
+      completion: '0.0000015',
+    },
+    ...overrides,
+  };
+}
+
+/**
+ * Creates a valid ModelsCache with a single model.
+ */
+export function createMockCache(overrides: Partial<ModelsCache> = {}): ModelsCache {
+  return {
+    models: [createValidModel()],
+    timestamp: Date.now() - 1000, // 1 second ago
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Activity/Analytics Fixtures
+// =============================================================================
+
+/**
+ * Creates a UTC date string (YYYY-MM-DD) relative to now.
+ * @param daysAgo - Days to subtract from current UTC date (0 for today)
+ * @returns Date string in YYYY-MM-DD format using UTC
+ */
+export function createTestDate(daysAgo: number): string {
+  const now = new Date();
+  const targetDate = new Date(now.getTime() - daysAgo * 24 * 60 * 60 * 1000);
+  return `${targetDate.getUTCFullYear()}-${String(targetDate.getUTCMonth() + 1).padStart(2, '0')}-${String(targetDate.getUTCDate()).padStart(2, '0')}`;
+}
+
+/**
+ * Creates an ActivityItem with sensible defaults.
+ * Use overrides to customize specific properties for test cases.
+ */
+export function createActivityItem(overrides?: Partial<ActivityItem>): ActivityItem {
+  return {
+    date: createTestDate(0),
+    model: 'gpt-4',
+    modelPermaslug: 'gpt-4-perma',
+    endpointId: 'ep-1',
+    usage: 5.0,
+    byokUsageInference: 0,
+    requests: 10,
+    promptTokens: 1000,
+    completionTokens: 100,
+    reasoningTokens: 0,
+    providerName: 'openai',
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// PiModelConfig Fixtures
+// =============================================================================
+
+/**
+ * Creates a valid PiModelConfig with sensible defaults.
+ */
+export function createPiModelConfig(overrides?: Partial<PiModelConfig>): PiModelConfig {
+  return {
+    id: 'test/model',
+    name: 'Test Model',
+    reasoning: false,
+    input: ['text'],
+    cost: {
+      input: 0.5,
+      output: 1.5,
+      cacheRead: 0,
+      cacheWrite: 0,
+    },
+    contextWindow: 128000,
+    maxTokens: 4096,
+    ...overrides,
+  };
+}

package/extensions/openrouter/__tests__/format.test.ts

@@ -1,6 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { aggregateUsage } from '../format.js';
 import { renderSpendSparkline } from '../chart.js';
+import { createTestDate, createActivityItem } from './fixtures.js';
 import type { ActivityItem } from '@openrouter/sdk/models/index.js';
 
 describe('aggregateUsage', () => {
@@ -13,24 +14,9 @@ describe('aggregateUsage', () => {
     // Get today's date in YYYY-MM-DD format using UTC date
     // This matches how the API returns dates (YYYY-MM-DD without timezone)
     // and how the implementation calculates 'today' (using UTC)
-    const now = new Date();
-    const todayStr = `${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, '0')}-${String(now.getUTCDate()).padStart(2, '0')}`;
+    const todayStr = createTestDate(0);
 
-    const analytics: ActivityItem[] = [
-      {
-        date: todayStr,
-        model: 'gpt-4',
-        modelPermaslug: 'gpt-4-perma',
-        endpointId: 'ep-1',
-        usage: 6.55,
-        byokUsageInference: 0,
-        requests: 10,
-        promptTokens: 1000,
-        completionTokens: 100,
-        reasoningTokens: 0,
-        providerName: 'openai',
-      },
-    ];
+    const analytics: ActivityItem[] = [createActivityItem({ date: todayStr, usage: 6.55 })];
 
     const result = aggregateUsage(credits, analytics);
 
@@ -43,37 +29,27 @@ describe('aggregateUsage', () => {
       totalCredits: 100,
     };
     // Use a date that's within the last 7 days of when the test runs.
-    // Get today's date in UTC and subtract a few days to ensure it's in the week window.
-    const now = new Date();
-    const testDate = new Date(now.getTime() - 3 * 24 * 60 * 60 * 1000); // 3 days ago
-    const date = `${testDate.getUTCFullYear()}-${String(testDate.getUTCMonth() + 1).padStart(2, '0')}-${String(testDate.getUTCDate()).padStart(2, '0')}`;
+    const date = createTestDate(3); // 3 days ago
     const analytics: ActivityItem[] = [
-      {
-        date: date,
+      createActivityItem({
+        date,
         model: 'model-1',
         modelPermaslug: 'model-1-perma',
         endpointId: 'ep-1',
         usage: 5.42,
-        byokUsageInference: 0,
-        requests: 10,
-        promptTokens: 1000,
-        completionTokens: 100,
-        reasoningTokens: 0,
         providerName: 'provider-1',
-      },
-      {
-        date: date,
+      }),
+      createActivityItem({
+        date,
         model: 'model-2',
         modelPermaslug: 'model-2-perma',
         endpointId: 'ep-2',
         usage: 3.11,
-        byokUsageInference: 0,
         requests: 5,
         promptTokens: 500,
         completionTokens: 50,
-        reasoningTokens: 0,
         providerName: 'provider-2',
-      },
+      }),
     ];
 
     const result = aggregateUsage(credits, analytics);
@@ -119,35 +95,30 @@ describe('aggregateUsage', () => {
       totalUsage: 10,
       totalCredits: 100,
     };
-    // Use a fixed date that's definitely in the past
-    const date = '2026-05-04';
+    // Use a dynamic date that's within the last 7 days
+    const date = createTestDate(3); // 3 days ago
     const analytics: ActivityItem[] = [
-      {
-        date: date,
+      createActivityItem({
+        date,
         model: 'gpt-4',
         modelPermaslug: 'gpt-4-perma',
-        endpointId: 'ep-1',
         usage: 5.0,
-        byokUsageInference: 0,
         requests: 5,
         promptTokens: 100,
         completionTokens: 50,
-        reasoningTokens: 0,
         providerName: 'openai',
-      },
-      {
-        date: date,
+      }),
+      createActivityItem({
+        date,
         model: 'claude-3',
         modelPermaslug: 'claude-3-perma',
         endpointId: 'ep-2',
         usage: 3.0,
-        byokUsageInference: 0,
         requests: 3,
         promptTokens: 60,
         completionTokens: 30,
-        reasoningTokens: 0,
         providerName: 'anthropic',
-      },
+      }),
     ];
 
     const result = aggregateUsage(credits, analytics);
@@ -218,32 +189,27 @@ describe('aggregateUsage', () => {
     };
     const date = '2026-05-01';
     const analytics: ActivityItem[] = [
-      {
-        date: date,
+      createActivityItem({
+        date,
         model: 'gpt-4',
         modelPermaslug: 'gpt-4-perma',
-        endpointId: 'ep-1',
         usage: 5.0,
-        byokUsageInference: 0,
         requests: 5,
         promptTokens: 100,
         completionTokens: 50,
-        reasoningTokens: 0,
         providerName: 'openai',
-      },
-      {
-        date: date,
+      }),
+      createActivityItem({
+        date,
         model: 'claude-3',
         modelPermaslug: 'claude-3-perma',
         endpointId: 'ep-2',
         usage: 3.0,
-        byokUsageInference: 0,
         requests: 3,
         promptTokens: 60,
         completionTokens: 30,
-        reasoningTokens: 0,
-        providerName: 'openai', // Same provider, different endpoint
-      },
+        providerName: 'openai',
+      }),
     ];
 
     const result = aggregateUsage(credits, analytics);

package/extensions/openrouter/__tests__/session.test.ts

@@ -31,89 +31,9 @@ describe('formatSessionId', () => {
 // Request Detection Tests
 // =============================================================================
 
-// Helper to create mock event
-function createEvent(
-  payload: Record<string, unknown>,
-  url?: string,
-  provider?: Record<string, unknown>,
-) {
-  const event: any = { payload };
-  if (url) event.url = url;
-  if (provider) event.provider = provider;
-  return event;
-}
-
-// Helper to create mock context
-function createContext(model: string | Record<string, unknown>) {
-  return { model } as any;
-}
-
 describe('isOpenRouterRequest', () => {
-  // Method 1: Check model string (e.g., "openrouter/anthropic/claude-3.5-sonnet")
-  it('detects OpenRouter by model prefix', () => {
-    const event = createEvent({ model: 'openrouter/anthropic/claude-sonnet-4' });
-    expect(isOpenRouterRequest(event, {})).toBe(true);
-  });
-
-  it('does not detect non-OpenRouter by model prefix', () => {
-    const event = createEvent({ model: 'anthropic/claude-sonnet-4' });
-    expect(isOpenRouterRequest(event, {})).toBe(false);
-  });
-
-  // Method 2: Check baseUrl from context.model
-  it('detects OpenRouter by baseUrl', () => {
-    const event = createEvent({ model: 'qwen/qwen3-coder-next' });
-    const ctx = createContext({ baseUrl: 'https://openrouter.ai/api/v1' });
-    expect(isOpenRouterRequest(event, ctx)).toBe(true);
-  });
-
-  it('does not detect non-OpenRouter by baseUrl', () => {
-    const event = createEvent({ model: 'qwen/qwen3-coder-next' });
-    const ctx = createContext({ baseUrl: 'https://api.anthropic.com' });
-    expect(isOpenRouterRequest(event, ctx)).toBe(false);
-  });
-
-  // Method 3: Check for ZDR provider (Shopify routes to OpenRouter via ZDR)
-  it('detects OpenRouter by ZDR provider', () => {
-    const event = createEvent({ model: 'qwen/qwen3-coder-next' }, undefined, { zdr: true });
-    expect(isOpenRouterRequest(event, {})).toBe(true);
-  });
-
-  it('does not detect non-ZDR provider', () => {
-    // Use provider name that won't match Method 5 (not "openrouter")
-    const event = createEvent({ model: 'qwen/qwen3-coder-next', provider: 'anthropic' });
-    expect(isOpenRouterRequest(event, {})).toBe(false);
-  });
-
-  // Method 4: Check URL
-  it('detects OpenRouter by URL', () => {
-    const event = createEvent(
-      { model: 'anthropic/claude-sonnet_4', messages: [] },
-      'https://openrouter.ai/api/v1/chat/completions',
-    );
-    expect(isOpenRouterRequest(event, {})).toBe(true);
-  });
-
-  it('does not detect non-OpenRouter by URL', () => {
-    const event = createEvent(
-      { model: 'anthropic/claude-sonnet_4', messages: [] },
-      'https://api.anthropic.com/v1/messages',
-    );
-    expect(isOpenRouterRequest(event, {})).toBe(false);
-  });
-
-  // Combined methods
-  it('detects by multiple methods simultaneously', () => {
-    const event = createEvent(
-      { model: 'openrouter/anthropic/claude-sonnet-4' },
-      'https://openrouter.ai/api/v1/chat/completions',
-    );
-    const ctx = createContext({ baseUrl: 'https://openrouter.ai/api/v1' });
-    expect(isOpenRouterRequest(event, ctx)).toBe(true);
-  });
-
   // =============================================================================
-  // Parameterized Tests - All Detection Methods
+  // Parameterized Tests - All Detection Methods (single source of truth)
   // =============================================================================
 
   const detectionCases: DetectionTestCase[] = [