@robhowley/pi-openrouter 0.9.1 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # pi-openrouter
 
-A [Pi](https://pi.dev/) extension for live OpenRouter visibility and environment sync: usage/account TUI overlays, automatic `session_id` tagging, user-scoped model catalog sync, and local model field overrides.
+A [Pi](https://pi.dev/) extension for live OpenRouter visibility and environment sync: usage/account TUI overlays, automatic `session_id` tagging, user-scoped model catalog sync, api key management, and local model field overrides.
 
 ## Installation
 
@@ -28,8 +28,9 @@ export OPENROUTER_MANAGEMENT_KEY=sk-or-...
 
 ```bash
 /openrouter usage                    # usage/spend overlay
-/openrouter account                  # credits, key limits, account health
+/openrouter account                  # credits, key limits, account health, key toggle UI
 /openrouter session                  # current OpenRouter session_id
+/openrouter api-key-create           # create an API key (management key required)
 /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
@@ -48,6 +49,8 @@ The sync uses OpenRouter’s authenticated user model catalog, so Pi can see the
 
 `/openrouter models-status`
 
+Model count and cache health live here. The Pi footer/status bar does not persistently show `OpenRouter {N} models` anymore.
+
 Example status output:
 
 ```text
@@ -61,7 +64,7 @@ To see why models were skipped:
 
 Skipped output may include a grouped suggestion when Pi can offer a safe next step, such as adding a local `contextWindow` override for incomplete metadata.
 
-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:
+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, `/openrouter models-status` will show:
 
 ```text
 OpenRouter models cached
@@ -101,10 +104,24 @@ The overlay shows:
 - **BYOK limit behavior**
 - **All visible keys**, when a management key is configured
 
-Select a key from the list to inspect its limit, usage, reset cadence, and BYOK behavior.
+Use `/openrouter account`, select a key with the arrow keys, press `t` to toggle enabled/disabled, and press Enter to confirm. You can still inspect the selected key's limit, usage, reset cadence, and BYOK behavior from the same overlay.
 
 <img src="https://raw.githubusercontent.com/robhowley/pi-userland/main/packages/pi-openrouter/img/openrouter-account-tui.png" alt="OpenRouter Account Overlay" width="600">
 
+## API key management
+
+API key management requires `OPENROUTER_MANAGEMENT_KEY`. `OPENROUTER_API_KEY` alone is not enough for key creation or account-level toggles.
+
+```bash
+/openrouter api-key-create <name> [limit=<usd|none>] [reset=<daily|weekly|monthly|none>] [byok=<incl|excl>] [workspace=<id>] [expires=<UTC ISO>]
+```
+
+Wrap `<name>` in quotes when it contains spaces, for example `/openrouter api-key-create "Team Key" limit=25`.
+
+To enable or disable a key, use `/openrouter account`, select the key with the arrow keys, press `t` to toggle it, and press Enter to confirm.
+
+When you create a key, Pi shows the returned secret once in an ephemeral overlay. Copy/store it immediately, do not expect Pi or OpenRouter to reveal it again, and avoid logging it or writing it to local files/debug output.
+
 ## Session tracking
 
 `pi-openrouter` automatically tags OpenRouter requests with a `session_id` derived from the Pi session ID.
@@ -122,7 +139,11 @@ pi:[uuid]
 
 ## Local usage tracking
 
-The extension logs completed OpenRouter turns to local JSONL files in `~/.pi/openrouter/usage/` to provide near-real-time usage data for "Today's spend" in the usage overlay. This supplements the OpenRouter Activity API, which typically has a delay.
+The extension logs completed OpenRouter turns to local JSONL files in `~/.pi/openrouter/usage/` to provide near-real-time usage data for the footer/status bar and for "Today's spend" in the usage overlay. This supplements the OpenRouter Activity API, which typically has a delay.
+
+When positive local spend exists in the last 30 UTC days, the footer/status bar shows local-only Today spend and a 30-day average multiplier, for example `OR $2.14 today · 1.3x 30d avg`.
+
+Model count and cache health remain available through `/openrouter models-status`.
 
 **Retention:** Local usage files are automatically cleaned up after 90 days.
 

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

@@ -0,0 +1,488 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@openrouter/sdk/sdk/sdk.js', () => ({
+  OpenRouter: vi.fn(),
+}));
+
+vi.mock('../client.js', () => ({
+  AuthError: class AuthError extends Error {
+    constructor(message: string) {
+      super(message);
+      this.name = 'AuthError';
+    }
+  },
+  ApiError: class ApiError extends Error {
+    statusCode?: number;
+
+    constructor(message: string, statusCode?: number) {
+      super(message);
+      this.name = 'ApiError';
+      if (statusCode !== undefined) {
+        this.statusCode = statusCode;
+      }
+    }
+  },
+}));
+
+function setKeys(apiKey?: string, mgmtKey?: string) {
+  if (apiKey === undefined) {
+    delete process.env['OPENROUTER_API_KEY'];
+  } else {
+    process.env['OPENROUTER_API_KEY'] = apiKey;
+  }
+
+  if (mgmtKey === undefined) {
+    delete process.env['OPENROUTER_MANAGEMENT_KEY'];
+  } else {
+    process.env['OPENROUTER_MANAGEMENT_KEY'] = mgmtKey;
+  }
+}
+
+function createMockSDKClient(
+  overrides: {
+    create?: ReturnType<typeof vi.fn>;
+    update?: ReturnType<typeof vi.fn>;
+  } = {},
+) {
+  return {
+    credits: { getCredits: vi.fn() },
+    workspaces: { list: vi.fn() },
+    apiKeys: {
+      create: overrides.create ?? vi.fn(),
+      update: overrides.update ?? vi.fn(),
+      list: vi.fn(),
+      getCurrentKeyMetadata: vi.fn(),
+    },
+  };
+}
+
+function createInventoryKey(overrides: Record<string, unknown> = {}) {
+  return {
+    name: 'Primary',
+    label: 'sk-or-v1-123',
+    status: 'healthy',
+    used: 10,
+    remaining: 90,
+    limit: 100,
+    resetCadence: 'monthly',
+    byok: 'incl',
+    hash: 'hash-1',
+    disabled: false,
+    workspaceName: 'Main Workspace',
+    spend: 10,
+    ...overrides,
+  };
+}
+
+function createCurrentKeyMetadata(overrides: Record<string, unknown> = {}) {
+  return {
+    byokUsage: 0,
+    byokUsageDaily: 0,
+    byokUsageMonthly: 0,
+    byokUsageWeekly: 0,
+    creatorUserId: null,
+    includeByokInLimit: true,
+    isFreeTier: false,
+    isManagementKey: true,
+    isProvisioningKey: false,
+    label: 'sk-or-v1-123',
+    limit: 100,
+    limitRemaining: 90,
+    limitReset: 'monthly',
+    usage: 10,
+    usageDaily: 0,
+    usageMonthly: 0,
+    usageWeekly: 0,
+    ...overrides,
+  };
+}
+
+describe('account-client api key management', () => {
+  beforeEach(() => {
+    vi.resetAllMocks();
+    vi.resetModules();
+    setKeys(undefined, undefined);
+  });
+
+  it('returns a missing-api-key inventory result when no OpenRouter key is configured', async () => {
+    const { getAllKeys } = await import('../account-client.js');
+
+    await expect(getAllKeys()).resolves.toEqual({
+      keys: [],
+      canManageKeys: false,
+      degradedReason: 'missing-api-key',
+    });
+  });
+
+  it('returns an empty but manageable inventory when key listing succeeds without keys', async () => {
+    setKeys(undefined, 'mgmt-key');
+
+    const mockClient = createMockSDKClient();
+    mockClient.workspaces.list.mockResolvedValue({
+      async *[Symbol.asyncIterator]() {
+        yield { result: { data: [] } };
+      },
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { getAllKeys } = await import('../account-client.js');
+
+    await expect(getAllKeys()).resolves.toEqual({
+      keys: [],
+      canManageKeys: true,
+    });
+  });
+
+  it('returns an explicit degraded inventory when key management is unavailable', async () => {
+    setKeys('plain-api-key', undefined);
+
+    const mockClient = createMockSDKClient();
+    mockClient.workspaces.list.mockRejectedValue({ status: 403, message: 'Forbidden' });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { getAllKeys } = await import('../account-client.js');
+
+    await expect(getAllKeys()).resolves.toEqual({
+      keys: [],
+      canManageKeys: false,
+      degradedReason: 'management-unavailable',
+    });
+  });
+
+  it('resolves an inventory-match relation from a unique inventory label match', async () => {
+    setKeys(undefined, 'mgmt-key');
+
+    const mockClient = createMockSDKClient();
+    mockClient.apiKeys.getCurrentKeyMetadata.mockResolvedValue({
+      data: createCurrentKeyMetadata({ label: 'sk-or-v1-active' }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { resolveCurrentKeyRelation } = await import('../account-client.js');
+
+    await expect(
+      resolveCurrentKeyRelation([
+        createInventoryKey({
+          name: 'default-space-key',
+          label: 'sk-or-v1-active',
+          hash: 'hash-active',
+          workspaceName: 'Default',
+        }),
+        createInventoryKey({
+          name: 'other-key',
+          label: 'sk-or-v1-other',
+          hash: 'hash-other',
+          workspaceName: 'Dev',
+        }),
+      ] as any),
+    ).resolves.toEqual({
+      kind: 'inventory-match',
+      hash: 'hash-active',
+      label: 'sk-or-v1-active',
+    });
+  });
+
+  it('resolves an external-provisioning relation when the current provisioning key is outside inventory', async () => {
+    setKeys(undefined, 'mgmt-key');
+
+    const mockClient = createMockSDKClient();
+    mockClient.apiKeys.getCurrentKeyMetadata.mockResolvedValue({
+      data: createCurrentKeyMetadata({
+        label: 'sk-or-v1-provisioning',
+        isProvisioningKey: true,
+      }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { resolveCurrentKeyRelation } = await import('../account-client.js');
+
+    await expect(
+      resolveCurrentKeyRelation([
+        createInventoryKey({
+          name: 'default-space-key',
+          label: 'sk-or-v1-active',
+          hash: 'hash-active',
+          workspaceName: 'Default',
+        }),
+      ] as any),
+    ).resolves.toEqual({
+      kind: 'external-provisioning',
+      label: 'sk-or-v1-provisioning',
+    });
+  });
+
+  it('returns an ambiguous-label relation when multiple inventory rows share the current label', async () => {
+    setKeys(undefined, 'mgmt-key');
+
+    const mockClient = createMockSDKClient();
+    mockClient.apiKeys.getCurrentKeyMetadata.mockResolvedValue({
+      data: createCurrentKeyMetadata({ label: 'sk-or-v1-active' }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { resolveCurrentKeyRelation } = await import('../account-client.js');
+
+    await expect(
+      resolveCurrentKeyRelation([
+        createInventoryKey({
+          name: 'default-space-key',
+          label: 'sk-or-v1-active',
+          hash: 'hash-active-1',
+          workspaceName: 'Default',
+        }),
+        createInventoryKey({
+          name: 'duplicate-label-key',
+          label: 'sk-or-v1-active',
+          hash: 'hash-active-2',
+          workspaceName: 'Dev',
+        }),
+      ] as any),
+    ).resolves.toEqual({
+      kind: 'ambiguous-label',
+      label: 'sk-or-v1-active',
+      matchingHashes: ['hash-active-1', 'hash-active-2'],
+    });
+  });
+
+  it('createApiKey sends the expected request body and returns the secret with normalized mutation state', async () => {
+    setKeys(undefined, 'mgmt-key');
+
+    const expiresAt = new Date('2026-06-01T00:00:00Z');
+    const mockClient = createMockSDKClient({
+      create: vi.fn().mockResolvedValue({
+        key: 'sk-or-v1-created-secret',
+        data: {
+          byokUsage: 0,
+          byokUsageDaily: 0,
+          byokUsageMonthly: 0,
+          byokUsageWeekly: 0,
+          createdAt: '2026-05-30T00:00:00.000Z',
+          creatorUserId: null,
+          disabled: false,
+          hash: 'hash-create',
+          includeByokInLimit: false,
+          label: 'sk-or-v1-created',
+          limit: null,
+          limitRemaining: null,
+          limitReset: null,
+          name: 'Team Key',
+          updatedAt: null,
+          usage: 0,
+          usageDaily: 0,
+          usageMonthly: 0,
+          usageWeekly: 0,
+          workspaceId: 'ws-1',
+          expiresAt,
+        },
+      }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { createApiKey } = await import('../account-client.js');
+    const result = await createApiKey({
+      name: 'Team Key',
+      limit: null,
+      limitReset: null,
+      includeByokInLimit: false,
+      workspaceId: 'ws-1',
+      expiresAt,
+    });
+
+    expect(mockClient.apiKeys.create).toHaveBeenCalledWith({
+      requestBody: {
+        name: 'Team Key',
+        limit: null,
+        limitReset: null,
+        includeByokInLimit: false,
+        workspaceId: 'ws-1',
+        expiresAt,
+      },
+    });
+    expect(result).toMatchObject({
+      key: 'sk-or-v1-created-secret',
+      keyState: {
+        name: 'Team Key',
+        hash: 'hash-create',
+        byok: 'excl',
+        resetCadence: 'never',
+        status: 'unbounded',
+      },
+    });
+    expect(result.keyState).not.toHaveProperty('workspaceName');
+  });
+
+  it('setApiKeyDisabled patches disabled status and returns normalized mutation state', async () => {
+    setKeys(undefined, 'mgmt-key');
+
+    const mockClient = createMockSDKClient({
+      update: vi.fn().mockResolvedValue({
+        data: {
+          byokUsage: 0,
+          byokUsageDaily: 0,
+          byokUsageMonthly: 0,
+          byokUsageWeekly: 0,
+          createdAt: '2026-05-30T00:00:00.000Z',
+          creatorUserId: null,
+          disabled: true,
+          hash: 'hash-disable',
+          includeByokInLimit: true,
+          label: 'sk-or-v1-disable',
+          limit: 100,
+          limitRemaining: 100,
+          limitReset: 'weekly',
+          name: 'Mutable Key',
+          updatedAt: null,
+          usage: 0,
+          usageDaily: 0,
+          usageMonthly: 0,
+          usageWeekly: 0,
+          workspaceId: 'ws-2',
+        },
+      }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { setApiKeyDisabled } = await import('../account-client.js');
+    const result = await setApiKeyDisabled('hash-disable', true);
+
+    expect(mockClient.apiKeys.update).toHaveBeenCalledWith({
+      hash: 'hash-disable',
+      requestBody: { disabled: true },
+    });
+    expect(result).toMatchObject({
+      name: 'Mutable Key',
+      hash: 'hash-disable',
+      disabled: true,
+      byok: 'incl',
+      resetCadence: 'weekly',
+      status: 'disabled',
+    });
+    expect(result).not.toHaveProperty('workspaceName');
+  });
+
+  it('requires OPENROUTER_MANAGEMENT_KEY for create operations', async () => {
+    setKeys('plain-api-key', undefined);
+
+    const { createApiKey } = await import('../account-client.js');
+
+    await expect(createApiKey({ name: 'Team Key' })).rejects.toMatchObject({
+      message: 'OPENROUTER_MANAGEMENT_KEY is required for API key management.',
+    });
+  });
+
+  it('maps unauthorized create errors to a management-key-required message', async () => {
+    setKeys(undefined, 'bad-mgmt-key');
+
+    const mockClient = createMockSDKClient({
+      create: vi.fn().mockRejectedValue({ status: 401, message: 'Unauthorized' }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { createApiKey } = await import('../account-client.js');
+
+    await expect(createApiKey({ name: 'Team Key' })).rejects.toMatchObject({
+      message:
+        'OPENROUTER_MANAGEMENT_KEY is required to create API keys. Set it to a valid management key.',
+    });
+  });
+
+  it('maps forbidden create errors to a management-key permissions message', async () => {
+    setKeys(undefined, 'mgmt-key');
+
+    const mockClient = createMockSDKClient({
+      create: vi.fn().mockRejectedValue({ status: 403, message: 'Forbidden' }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { createApiKey } = await import('../account-client.js');
+
+    await expect(createApiKey({ name: 'Team Key' })).rejects.toMatchObject({
+      message:
+        'OPENROUTER_MANAGEMENT_KEY does not have permission to create API keys. Set it to a valid management key.',
+      statusCode: 403,
+    });
+  });
+
+  it('requires OPENROUTER_MANAGEMENT_KEY for toggle operations', async () => {
+    setKeys('plain-api-key', undefined);
+
+    const { setApiKeyDisabled } = await import('../account-client.js');
+
+    await expect(setApiKeyDisabled('hash-disable', true)).rejects.toMatchObject({
+      message: 'OPENROUTER_MANAGEMENT_KEY is required for API key management.',
+    });
+  });
+
+  it('maps unauthorized disable errors to a management-key-required message', async () => {
+    setKeys(undefined, 'bad-mgmt-key');
+
+    const mockClient = createMockSDKClient({
+      update: vi.fn().mockRejectedValue({ status: 401, message: 'Unauthorized' }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { setApiKeyDisabled } = await import('../account-client.js');
+
+    await expect(setApiKeyDisabled('hash-disable', true)).rejects.toMatchObject({
+      message:
+        'OPENROUTER_MANAGEMENT_KEY is required to disable API keys. Set it to a valid management key.',
+    });
+  });
+
+  it('maps forbidden enable errors to a management-key permissions message', async () => {
+    setKeys(undefined, 'mgmt-key');
+
+    const mockClient = createMockSDKClient({
+      update: vi.fn().mockRejectedValue({ status: 403, message: 'Forbidden' }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { setApiKeyDisabled } = await import('../account-client.js');
+
+    await expect(setApiKeyDisabled('hash-enable', false)).rejects.toMatchObject({
+      message:
+        'OPENROUTER_MANAGEMENT_KEY does not have permission to enable API keys. Set it to a valid management key.',
+      statusCode: 403,
+    });
+  });
+
+  it('preserves not-found update messages and status codes', async () => {
+    setKeys(undefined, 'mgmt-key');
+
+    const mockClient = createMockSDKClient({
+      update: vi.fn().mockRejectedValue({ status: 404, message: 'Key not found' }),
+    });
+
+    const { OpenRouter } = await import('@openrouter/sdk/sdk/sdk.js');
+    vi.mocked(OpenRouter).mockImplementation(() => mockClient as any);
+
+    const { setApiKeyDisabled } = await import('../account-client.js');
+
+    await expect(setApiKeyDisabled('missing-hash', true)).rejects.toMatchObject({
+      message: 'Key not found',
+      statusCode: 404,
+    });
+  });
+});