mirror of
https://github.com/browseros-ai/BrowserOS.git
synced 2026-05-13 15:46:22 +00:00
8548bcf50a
* feat: add credit-based tracking for BrowserOS provider Send X-BrowserOS-ID header on all LLM requests through the BrowserOS gateway for per-installation credit tracking. Handle 429 CREDITS_EXHAUSTED as non-retryable. Add GET/PUT /credits endpoints to check and manage credit balance. * docs: add credits tracking UI design Design for showing credit balance in side panel chat header (color-coded badge) and a dedicated Usage & Billing settings page. Credits refresh after each completed message turn or on exhaustion error. * docs: add credits tracking UI implementation plan 8-task plan covering useCredits hook, CreditBadge component, ChatHeader integration, message completion refresh, ChatError CREDITS_EXHAUSTED handling, Usage & Billing settings page, and route/sidebar registration. * feat: add useCredits React Query hook * feat: add CreditBadge component with color thresholds * feat: show credit badge in chat header for BrowserOS provider * feat: refresh credits after chat message completion and on error * feat: handle CREDITS_EXHAUSTED error in chat * feat: add Usage & Billing settings page * feat: register usage page route and sidebar entry * fix: lint and formatting fixes for credit tracking UI * fix: separate credits exhausted from Kimi rate limit in ChatError, redesign Usage page * chore: remove PUT /credits endpoint and setCredits function * fix: extract shared credit colors, add error state to UsagePage, use dailyLimit from gateway * fix: make dailyLimit required in CreditsInfo (gateway always returns it) * feat: gate credits UI behind CREDITS_SUPPORT feature flag (server >= 0.0.78)
59 lines
2.3 KiB
Markdown
59 lines
2.3 KiB
Markdown
# Credits Tracking UI Design
|
||
|
||
## Overview
|
||
|
||
Surface credit balance to users across two locations: a compact badge in the side panel chat header, and a dedicated Usage & Billing settings page. Credits refresh after each completed message turn or on error.
|
||
|
||
## 1. Side Panel — Credit Badge
|
||
|
||
**Location:** Chat header, next to provider selector. Only visible when provider is `browseros`.
|
||
|
||
**Display:**
|
||
- Coin/credit icon + remaining count (e.g., "87")
|
||
- Color-coded by threshold:
|
||
- Green: >30 credits
|
||
- Yellow/orange: 1–30 credits
|
||
- Red: 0 credits
|
||
- Clicking the badge navigates to the Usage & Billing settings page
|
||
|
||
**Update triggers:**
|
||
- Message turn completes successfully (agent finishes all tool calls and responds)
|
||
- CREDITS_EXHAUSTED error mid-turn (badge syncs to 0, error shown in chat)
|
||
|
||
## 2. Settings — Usage & Billing Page
|
||
|
||
**Sidebar entry:** "Usage & Billing" in the "Other" section (icon: CreditCard or Coins).
|
||
|
||
**Route:** `/settings/usage`
|
||
|
||
**Content:**
|
||
- Credits card: large display of remaining credits (e.g., "87 / 100") with color-coded progress bar
|
||
- Reset info: "Resets daily at midnight UTC" with last reset date
|
||
- Credit cost: "1 credit per request"
|
||
- Placeholder section: "Need more credits?" with disabled "Add Credits" button (future payment/recharge)
|
||
|
||
## 3. Data Flow
|
||
|
||
**Hook:** `useCredits()` — React Query hook fetching `GET /credits` from the agent server.
|
||
|
||
**Refresh strategy:**
|
||
- Refetch after each completed message turn (`onFinish` callback in chat session)
|
||
- Refetch on CREDITS_EXHAUSTED error
|
||
- Refetch on window focus (React Query default)
|
||
- No aggressive polling
|
||
|
||
**State sharing:** Credits query is global (React Query cache). Both side panel badge and settings page read from the same cache key.
|
||
|
||
## 4. Error Handling (0 credits)
|
||
|
||
When credits are exhausted mid-conversation:
|
||
- Chat stream shows error via existing `ChatError.tsx` pattern: "Daily credits exhausted. Resets at midnight UTC." with link to Usage & Billing page
|
||
- Header badge turns red (0 credits)
|
||
- Chat input stays enabled — user can switch to a different provider
|
||
|
||
## 5. Future Hooks
|
||
|
||
- "Add Credits" button on Usage & Billing page (currently disabled placeholder)
|
||
- Payment integration will live entirely within the Usage & Billing page
|
||
- Credit badge could show a "+" icon when balance is low, linking to recharge
|