feat(billing): expose credit usage log in Billing settings

[waleedlatif1]

Summary

• Add a "Credit usage" section under Billing settings, below Invoices — a paginated, period-filterable list of individual credit-consuming events (model, tool, fixed charges), shown to every plan except Enterprise
• The backend query already existed (getUserUsageLogs) but the /api/users/me/usage-logs route was dead/unused — wired it up with a proper getUsageLogsContract, a useUsageLogs infinite-query hook, and an emcn-styled UI section matching the existing Invoices list
• Fixed a stale query-param enum on the route that only allowed 3 of the real 9 usage_log sources
• Extracted formatCreditsLabel in conversion.ts so the credit-usage rows, the billing cost breakdown, and the trace view all share one formatter instead of diverging

Type of Change

• New feature

Testing

• Added route.test.ts (5 tests: auth, dollar→credit conversion, invalid period, start-date resolution per period)
• Verified live: ran the app against a local seeded DB, forged a Better Auth session, drove it with Playwright — confirmed the section is hidden for an Enterprise-plan user, correctly renders and reconciles totals for a Free-plan user with real usage rows, and the period dropdown re-filters correctly
• check:api-validation, typecheck, and full test suite all pass

Checklist

• Code follows project style guidelines
• Self-reviewed my changes
• Tests added/updated and passing
• No new warnings introduced
• I confirm that I have read and agree to the terms outlined in the Contributor License Agreement (CLA)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
docs	Skipped		Jul 3, 2026 8:13pm

[cursor]

PR Summary

Medium Risk
Touches a user billing read API (response shape and source filter) and displays usage ledger data; changes are scoped to authenticated self-service with new route tests and no payment writes.

Overview
Adds a Credit usage section to Billing settings (non-Enterprise) so users can see paginated, period-filtered credit events with totals and humanized source labels.

The /api/users/me/usage-logs handler is refactored to validate via getUsageLogsContract and parseRequest, maps dollar costs to credits-only responses (creditCost, totalCredits, bySourceCredits), trims log fields, and expands allowed source values to match the full usage ledger. Period filtering is centralized in resolveStartDate.

Client wiring includes useUsageLogs (infinite query + contract client), URL-synced period via nuqs, and formatCreditsLabel shared with existing dollar-based credit formatting.

^{Reviewed by Cursor Bugbot for commit 73679b1. Configure here.}

[greptile-apps]

Greptile Summary

Wires up the previously-dead /api/users/me/usage-logs route with a proper getUsageLogsContract, expands its source enum from 3 to 9 values, and adds a paginated "Credit usage" section to Billing settings (hidden for Enterprise plans). A shared formatCreditsLabel helper is extracted in conversion.ts so the new log rows, the existing breakdown, and the trace view all pluralize credits identically.

• Route refactor (route.ts): adopts parseRequest/contract validation, a clean resolveStartDate helper, and strips category from the API response; dollar→credit conversion and summary aggregation are correct.
• Infinite-query hook + key factory (usage-logs.ts, usage-log-keys.ts): key factory is in a standalone non-'use client' module per project convention; period is in the query key, pageParam/signal correctly exempt; keepPreviousData applies because the key varies.
• UI section (credit-usage-section.tsx, search-params.ts): period filter is nuqs-backed (replace-history, clear-on-default); totalCredits from pages[0] is the correct full-period aggregate since getUserUsageLogs runs its summary query without the cursor constraint.

Confidence Score: 5/5

Safe to merge — the change is additive (new UI section + contract), the backend query logic was pre-existing, and the gating on !isEnterprise is straightforward.

All changed paths are additive; the route refactor is well-tested (5 targeted test cases), the contract expansion correctly mirrors the real DB enum, and the infinite-query wiring follows established project patterns without touching any shared billing state.

No files require special attention.

Important Files Changed

Filename	Overview
apps/sim/app/api/users/me/usage-logs/route.ts	Rewrites the handler using parseRequest + getUsageLogsContract; cleans up dollar→credit conversion and removes the try/catch in favour of withRouteHandler; no issues found.
apps/sim/app/workspace/[workspaceId]/settings/components/billing/components/credit-usage-section/credit-usage-section.tsx	New paginated credit-usage UI; totalCredits correctly uses pages[0] which holds the full-period aggregate (backend runs a separate summary query); SOURCE_LABELS covers all 9 enum values; minor display inconsistency for sub-$0.005 entries (formatCreditsLabel has no <1 credit guard).
apps/sim/hooks/queries/usage-logs.ts	Infinite-query hook with explicit staleTime, keepPreviousData for period transitions, and correct signal forwarding; key factory lives in the non-'use client' utils file per project rules.
apps/sim/hooks/queries/utils/usage-log-keys.ts	Standalone key factory (no 'use client') following the folder-keys / table-keys pattern; source slot is present in the list key for future use.
apps/sim/lib/api/contracts/user.ts	Adds usageLogSourceSchema (all 9 sources), usageLogPeriodSchema, response schema, and getUsageLogsContract; expands the stale 3-value source enum to cover all real sources.
apps/sim/lib/billing/credits/conversion.ts	Extracts formatCreditsLabel as a shared building block; formatCreditCost now delegates to it, eliminating duplication; no regressions.
apps/sim/app/workspace/[workspaceId]/settings/components/billing/billing.tsx	Adds CreditUsageSection below Invoices, gated on !subscription.isEnterprise; minimal, correct change.
apps/sim/app/api/users/me/usage-logs/route.test.ts	New test file covers auth, dollar→credit conversion, invalid period rejection, and period→startDate resolution; all five cases are solid.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
participant UI as CreditUsageSection
participant nuqs as nuqs URL state
participant RQ as React Query
participant API as GET /api/users/me/usage-logs
participant DB as getUserUsageLogs
UI->>nuqs: read period default 30d
UI->>RQ: useUsageLogs period
RQ->>API: "GET ?period=30d&limit=25"
API->>DB: paginated logs query with cursor
API->>DB: summary aggregate query no cursor
DB-->>API: logs page plus full-period summary
API-->>RQ: logs summary.totalCredits pagination
RQ-->>UI: pages[0] totalCredits shown logs rendered
UI->>RQ: fetchNextPage cursor
RQ->>API: "GET ?period=30d&limit=25&cursor=id"
API->>DB: paginated logs cursor filtered
API->>DB: summary aggregate no cursor
DB-->>API: next page plus same full-period summary
API-->>RQ: additional logs appended
UI->>nuqs: user selects 7d
nuqs-->>UI: period equals 7d replace history
UI->>RQ: useUsageLogs period 7d new queryKey
RQ->>API: "GET ?period=7d&limit=25"
API-->>RQ: new page set
RQ-->>UI: fresh data replaces keepPreviousData placeholder

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
participant UI as CreditUsageSection
participant nuqs as nuqs URL state
participant RQ as React Query
participant API as GET /api/users/me/usage-logs
participant DB as getUserUsageLogs
UI->>nuqs: read period default 30d
UI->>RQ: useUsageLogs period
RQ->>API: "GET ?period=30d&limit=25"
API->>DB: paginated logs query with cursor
API->>DB: summary aggregate query no cursor
DB-->>API: logs page plus full-period summary
API-->>RQ: logs summary.totalCredits pagination
RQ-->>UI: pages[0] totalCredits shown logs rendered
UI->>RQ: fetchNextPage cursor
RQ->>API: "GET ?period=30d&limit=25&cursor=id"
API->>DB: paginated logs cursor filtered
API->>DB: summary aggregate no cursor
DB-->>API: next page plus same full-period summary
API-->>RQ: additional logs appended
UI->>nuqs: user selects 7d
nuqs-->>UI: period equals 7d replace history
UI->>RQ: useUsageLogs period 7d new queryKey
RQ->>API: "GET ?period=7d&limit=25"
API-->>RQ: new page set
RQ-->>UI: fresh data replaces keepPreviousData placeholder

Loading

_{Reviews (6): Last reviewed commit: "improvement(billing): move credit usage ..." | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 89fe7e7. Configure here.}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

1 issue from previous review remains unresolved.

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 73679b1. Configure here.}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 73679b1. Configure here.}