feat(openrouter): add OpenRouter usage provider

[robinebers]

TL;DR

Adds a native OpenRouter usage provider to the Swift edition (closes #578): a Credits meter + Balance above the fold, with daily/weekly/monthly spend and an optional per-key cap below the caret. Along the way it fixes a latent layout bug where below-the-fold metrics added after release surfaced above the fold for existing users.

What was happening

• OpenRouter (New Provider: openrouter.ai #578) had no provider in the Swift edition — the branch linked in the issue is the legacy Tauri JS plugin, not portable as-is.
• Separately: the "Shown on expand" (below-the-fold) membership was only seeded on a genuinely fresh install. A default-expanded metric added in a later release was auto-enabled for existing layouts but landed above the fold, ignoring DefaultLayout.expandedMetricIDs. OpenRouter is the first provider to add several below-fold metrics post-release, so it's the first to expose this.

What this changes

New OpenRouter provider (Sources/OpenUsage/Providers/OpenRouter/)

• OpenRouterAuthStore — reads the API key from OPENROUTER_API_KEY (or OPENROUTER_KEY), else ~/.config/openusage/openrouter.json (apiKey/api_key/key, or a plain-text key file). OpenRouter is the first provider needing a user-supplied key — it has no companion CLI/app that leaves a credential behind. The config file is the reliable path since the GUI app doesn't inherit the shell env.
• OpenRouterUsageClient — GET /api/v1/credits (required) + GET /api/v1/key (best-effort), Bearer auth.
• OpenRouterUsageMapper — Credits meter (total_usage / total_credits), Balance (remaining), Today/This Week/This Month spend (real $0.00 shown, never "No data"), optional Key Limit meter when the key has a cap. Tier (is_free_tier) maps to the snapshot plan ("Pay as you go" / "Free tier"), not a separate tile.
• Registered in AppContainer (alphabetical tail), with ErrorCategory conformances, a provider mark (Resources/ProviderIcons/openrouter.svg) + SF Symbol fallback.
• Default layout: Credits (primary, pinned) + Balance primary; Today / This Week / This Month / Key Limit secondary. Confirmed placement with the owner.
• Docs page (docs/providers/openrouter.md) + README entry.

Layout migration fix (LayoutStore)

• seedNewDefaultMetrics now reports the ids it newly auto-enabled; init unions the default-expanded ones into expandedMetricIDs so they enter below the caret on upgrade. Guarded to brand-new metrics only, so a metric the user already lived with is never silently hidden. This is broader than OpenRouter — it corrects placement for any future below-fold metric addition.

Heads-up

• First user-supplied-key provider. A deliberate departure from the "read credentials already on the machine, never paste a token" principle, unavoidable since OpenRouter exposes nothing locally. No browser cookies are read.
• The LayoutStore change touches the shared seeding path for every provider — the new regression test plus the existing 40 LayoutStore tests cover it, but worth a careful look.
• total_credits is lifetime credits purchased, so the Credits meter is a lifetime burn-down (subtitle "$X purchased"), not a recurring quota. Balance is the more glanceable number and is also primary.

Tests

• 14 new tests for the provider (auth-source precedence, mapper shapes incl. real-zero spend / missing-/key / auth failure, full refresh).
• 1 new LayoutStore regression test for the upgrade path.
• Full suite green: 506 tests, 0 failures.
• Verified live against a real OpenRouter account via the local API (/v1/usage/openrouter): plan: Pay as you go, Credits $178.20 / $277.47, Balance $99.27, spend rows real zeros, Key Limit correctly omitted (no cap). Confirmed in the running app that the four spend rows seed below the caret and Credits/Balance stay primary.

Screenshots

---

Note

Medium Risk
OpenRouter is isolated, but LayoutStore touches shared seeding/persistence for all providers; API keys are read from disk/env and sent as Bearer tokens to OpenRouter only.

Overview
Adds OpenRouter as a first-class provider: API keys from ~/.config/openusage/openrouter.json (over env), independent GET /credits and GET /key calls with partial-failure tolerance, and widgets for credits, balance, period spend, and optional key limit. Registered in the app with default layout (Credits pinned primary), icon, telemetry error mapping, and provider docs.

LayoutStore changes fix upgrade behavior when new default-expanded metrics ship: auto-enabled metrics from seedNewDefaultMetrics are added to expandedMetricIDs, and the expand-on-enable queue is persisted (expandOnEnableKey) so legacy optional metrics still land below the caret, explicit drags consume queue entries across relaunch, and undo/reset persist the queue.

README now lists OpenRouter and notes it is the exception that requires a user API key.

^{Reviewed by Cursor Bugbot for commit f5f55a0. Bugbot is set up for automated code reviews on this repo. Configure here.}

Confidence Score: 5/5

Safe to merge. The new OpenRouter provider is well-isolated, and the LayoutStore migration fix is carefully guarded to only affect brand-new metrics.

The two-endpoint fetch is correctly resilient to partial failures (each leg is independent). The expandOnEnableKey persistence correctly solves the legacy-layout upgrade path that the previous review raised, and the three new regression tests confirm all three branches. The default layout placement (Credits/Balance primary, period spend and Key Limit secondary) matches the documented intent. No data-loss, auth, or layout-corruption paths were found.

No files require special attention.

Comments Outside Diff (1)

1. Tests/OpenUsageTests/LayoutStoreTests.swift, line 497-529 (link)

   Migration fix has an untested path that changes defaultExpandedOnEnableIDs behaviour

   The new regression test exercises the branch where layout.expandedMetrics is already saved (savedExpanded exists). There is a second branch — hasStoredLayout && !savedExpanded — for users who have a stored layout but predate the expanded-metrics feature, where expandedMetricIDs starts empty and initialDefaultExpandedOnEnableIDs is populated with unplaced default-expanded metrics such as cursor.requests.

   For users in that branch, the migration fix now unions the new OpenRouter below-fold metrics into expandedMetricIDs and persists that set. On the next launch they enter the savedExpanded path, where initialDefaultExpandedOnEnableIDs is always seeded as []. Any default-expanded metric they hadn't yet enabled (e.g. cursor.requests) will then appear above the fold when first enabled, instead of below the caret as originally intended. The effect is narrow — users must be in that exact old state and then enable one of those metrics after upgrading — but a test covering this path would confirm the intended trade-off is deliberate.

   Prompt To Fix With AI

   This is a comment left during a code review.
   Path: Tests/OpenUsageTests/LayoutStoreTests.swift
   Line: 497-529
   
   Comment:
   **Migration fix has an untested path that changes `defaultExpandedOnEnableIDs` behaviour**
   
   The new regression test exercises the branch where `layout.expandedMetrics` is already saved (`savedExpanded` exists). There is a second branch — `hasStoredLayout && !savedExpanded` — for users who have a stored layout but predate the expanded-metrics feature, where `expandedMetricIDs` starts empty and `initialDefaultExpandedOnEnableIDs` is populated with unplaced default-expanded metrics such as `cursor.requests`.
   
   For users in that branch, the migration fix now unions the new OpenRouter below-fold metrics into `expandedMetricIDs` and persists that set. On the next launch they enter the `savedExpanded` path, where `initialDefaultExpandedOnEnableIDs` is always seeded as `[]`. Any default-expanded metric they hadn't yet enabled (e.g. `cursor.requests`) will then appear above the fold when first enabled, instead of below the caret as originally intended. The effect is narrow — users must be in that exact old state and then enable one of those metrics after upgrading — but a test covering this path would confirm the intended trade-off is deliberate.
   
   How can I resolve this? If you propose a fix, please make it concise.

   

_{Reviews (5): Last reviewed commit: "fix(layout): persist the expand-on-enabl..." | Re-trigger Greptile}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 180e851. Configure here.}

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.

[validatedev]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 35453c0d09

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

robinebers has reached the 50-review limit for trial accounts. To continue receiving code reviews, upgrade your plan.