85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
# UnoRouter Balance — Hermes Desktop Plugin
|
|
|
|
Statusbar chip for [Hermes Agent](https://hermes-agent.nousresearch.com) Desktop
|
|
showing how much UnoRouter credit you have left, plus a popover with the full
|
|
breakdown.
|
|
|
|
## What it shows
|
|
|
|
Statusbar readout — `left/total (pct%)` of your spendable budget:
|
|
|
|
```
|
|
7.02/10 (70%)
|
|
```
|
|
|
|
Click opens a popover:
|
|
|
|
- **UnoRouter** heading with a refresh button
|
|
- **Available** — total spendable, with a progress bar
|
|
- Subscription credit, plan name, time to weekly reset
|
|
- Wallet balance, lifetime spend, request count
|
|
|
|
Hover shows a one-line tip; details live in the popover only.
|
|
|
|
## Install
|
|
|
|
1. Create an **access token** (not an `sk-` API key) at
|
|
unorouter.com → Settings → Security → API access.
|
|
2. Copy this folder to `$HERMES_HOME/desktop-plugins/unorouter-balance/`.
|
|
- Windows: `%LOCALAPPDATA%\hermes\desktop-plugins\unorouter-balance\`
|
|
- Linux/macOS: `~/.hermes/desktop-plugins/unorouter-balance/`
|
|
- The folder name must match the plugin id.
|
|
3. Either paste the token into `DEFAULT_TOKEN` at the top of `plugin.js`, or
|
|
run ⌘K → **UnoRouter: set access token** (persisted per plugin).
|
|
4. ⌘K → **Reload desktop plugins**.
|
|
|
|
The app watches the folder, so later saves hot-reload in place.
|
|
|
|
## Two credit pools
|
|
|
|
This trips people up. UnoRouter keeps two separate pools:
|
|
|
|
| Pool | Source | Expiry |
|
|
|---|---|---|
|
|
| Subscription credit | weekly delivery on a plan | resets weekly, does **not** carry over |
|
|
| Wallet | one-time top-ups | never expires |
|
|
|
|
`/api/user/self` → `quota` is the **wallet only**. It reads `0` on an active
|
|
subscription, so a naive plugin reports "$0.00" to a paying subscriber. This
|
|
plugin adds the subscription remainder (`/api/subscription/self`) and shows the
|
|
sum, because `billing_preference` is `subscription_first` and the subscription
|
|
carries `allow_wallet_overflow: true`.
|
|
|
|
## API
|
|
|
|
Both endpoints take the access token as `Authorization: Bearer <token>`.
|
|
Quota units: `500000 == $1`.
|
|
|
|
```
|
|
GET /api/user/self # wallet quota, lifetime spend, request count
|
|
GET /api/subscription/self # subscription credit, next reset, plan title
|
|
```
|
|
|
|
`/api/subscription/self` is **not in the public docs**. It answers 200.
|
|
Dead ends: `/api/subscription`, `/api/billing`, `/api/plan` → 404;
|
|
`/api/user/subscription`, `/api/user/plan` → 403.
|
|
|
|
Most failures answer HTTP 200 with `success: false` — check that field, not the
|
|
status code. Real 401/403 means a bad or revoked token.
|
|
|
|
## Refresh
|
|
|
|
Polls every 5 minutes via React Query (`REFRESH_MS`). Background polling is off
|
|
by default, so an unfocused window doesn't tick. Manual refresh: the button in
|
|
the popover, or ⌘K → **UnoRouter: refresh balance**.
|
|
|
|
## Palette commands
|
|
|
|
- `UnoRouter: refresh balance`
|
|
- `UnoRouter: set access token`
|
|
- `UnoRouter: open billing page`
|
|
|
|
## Note on the token
|
|
|
|
`DEFAULT_TOKEN` in this repo is empty on purpose — don't commit a live token.
|