feat(cursor): spend view toggle for included vs billed usage

[maxmilian]

TL;DR

Adds a Cursor Spend View toggle (All / Included / API Usage) so the spend tiles and Usage Trend can show plan-included usage, billed on-demand usage, or the combined picture — implementing #609.

Closes #609.

What was happening

• Cursor's export marks each row as plan-Included or billed (a dollar Cost), but OpenUsage dropped the Cost column and summed every row together.
• The Today / Yesterday / Last 30 Days tiles and the Usage Trend therefore always mixed both kinds, so a user couldn't answer "how much of my included plan did I use?" vs "how much on-demand spend did I rack up?"

What this changes

• Parse billing kind — CursorUsageCSV reads the Cost column into a new CursorBillingKind (included / billed / unknown). The column is optional: exports without it still parse, with rows left .unknown.
• Spend View setting — new CursorSpendViewSetting (all / included / api), a UserDefaultsBacked enum like TimeFormatSetting, persisted per device, default all (unchanged behavior).
• Filtering — CursorUsageMapper.appendSpendLines takes the view and filters rows before aggregating; a view with no matching rows reads "No data" rather than a fabricated $0. Filtered rows drop out of tiles, trend, and the model breakdown alike.
• Provider — CursorProvider reads the setting at each refresh (so a flip applies on the next snapshot) and logs when a Cost-less export can't satisfy a non-All view.
• UI — a Cursor-only Spend View card in the Cursor Customize detail (CursorSpendViewSection), following the APIKeysSection pattern; changing it forces a refresh.
• Docs — docs/providers/cursor.md gains a Spend View subsection.

Heads-up

• Per the issue's open question: the bounded meters (Total / Auto / API Usage %) intentionally stay as Cursor reports them — they come from Cursor's live API, not the export, and re-deriving them locally would contradict the dashboard. The toggle scopes to the CSV-derived spend tiles + trend only.
• unknown rows (Cost-less exports) count only under All Usage; assigning them to a side would fake the split.

Tests

• CursorSpendViewSetting filtering: All = $7 / 700 tok, Included = $1 / 100 tok, API = $2 / 200 tok on a mixed day; empty-after-filter → "No data".
• Cost column parsing: Included/included → included, \$1.23/1.23 → billed, empty/absent column → unknown.
• Full suite green apart from the 4 Codex tests already red on a clean main.

Screenshots

Cursor Customize detail → new Spend View card with the three-way picker:

🤖 Generated with Claude Code

https://claude.ai/code/session_019dpF8491eHK8reiuJ8vMxB

[robinebers]

Nice work — architecture and default look right (All Usage / .all preserves today's combined spend tiles; meters stay API-sourced; Cost-less rows only count under All).

Follow-up I'd take:

1. Fix the label wrap — Spend Tiles Show breaks onto two lines even with empty space before the picker. SwiftUI is letting the Text wrap so the Spacer can expand. Pin it with .lineLimit(1) (or .fixedSize(horizontal: true, vertical: false)).
2. Shorten the row copy — the section is already titled Spend View, so Spend Tiles Show is redundant. Something like Show (or reuse Settings' plain row+picker shape) would read cleaner and reduce wrap pressure.
3. Optional naming polish — picker option API Usage collides with Cursor's existing API Usage meter. Worth a later pass if that confuses people in practice (On-Demand / Billed?).

Not blocking on (3); (1)–(2) are the ones I'd land before or right after merge.

[maxmilian]

Thanks for the review! Pushed 4ac3e81 addressing (1) and (2) together:

• Row label is now just Show — the Spend View header already names the card, so the longer copy was redundant.
• Pinned it with .fixedSize(horizontal: true, vertical: false) so the trailing Spacer can't squeeze the Text into a wrap.

On (3): agreed that API Usage colliding with Cursor's own API Usage meter is worth clearing up — I'd lean Billed (it's the on-demand/over-plan spend). Happy to fold that rename in here if you'd like it now, or leave it for a follow-up per your call since it touches the option labels users will see.

[maxmilian]

Folded (3) in and rebased onto current main — 23 commits behind; the only two that touched these files are the Account-first passes over CustomizeProviderDetailView, which don't overlap the spend view, so the rebase was clean.

On (3) specifically: I asked back on 07-18 whether you wanted the rename now or left as a follow-up. Rather than hold the PR waiting on an answer, I've made the call and kept it trivially reversible — it's its own commit (53176f5), so dropping it leaves (1)–(2) intact if you'd rather ship the rename separately or not at all.

API Usage → Billed. I renamed the enum case along with the label (case api → case billed) instead of only the user-facing string, so the code doesn't carry two words for the same side. The raw value moves with it; nothing to migrate, since this hasn't shipped.

Deliberately left alone: the bounded API Usage % meter, and the doc sentence describing Cursor's own export terminology ("plan-included vs billed API usage"). The collision was the picker borrowing the meter's name — Cursor's term for the billing side isn't itself wrong, so only the option that sat next to the meter needed to move.

swift build clean; swift test --filter CursorSpend 14/14 green.