dsh-billing-badge
English | 中文
Billing season and account balance for the DeepSeek Harness web GUI. A pill in the
composer's statistics row, immediately after the native Cache hit reading, that
opens a small panel with the full picture.
2288M tok · Cache hit 99.8% · ● Off-peak · 2h13m
The pill in the composer statistics row and the panel it opens
What it shows
| Where | What |
|---|
| The pill | a coloured dot (amber for peak, green for off-peak), the season, and the time until it flips |
| The panel (click) | billing season, next switch with the Beijing wall clock, current Beijing time, account balance with its currency, the granted and topped-up split when the account has one, and a refresh button |
The season rule is the published one: peak is Beijing time, Monday to Friday,
09:00-12:00 and 14:00-18:00. Everything else, including all of Saturday and Sunday,
is off-peak at half price.
The balance
The numbers come from the official GET /user/balance endpoint, and the three of them
mean different things:
total_balance = granted_balance + topped_up_balance
total_balance, shown as Account balance, is everything you can spend.granted_balance, shown as Granted, is credit DeepSeek gave you. The endpoint
reports only the part that has not expired, so a lapsed grant disappears from this
row on its own.topped_up_balance, shown as Topped up, is money you paid in.
The panel names the two parts only when the account is actually split. With no grant the
topped-up amount is the whole balance, so the split would repeat the account balance row
above it, and that account shows one row instead. Granted appears as soon as the
endpoint reports one.
is_available is a top-level field of the response and answers one question: is the
balance enough for API calls. The panel adds a warning row when the answer is no, and
stays quiet otherwise, because the flag is true for every funded account.
The currency is taken from the response, never assumed: an account reporting USD is
not labelled with a CNY sign.
Why another one
Two community plugins cover parts of this, and both taught something:
- dsh-price-phase shows the season.
Its countdown once pointed at Saturday 09:00 after Friday close, an event that does
not happen, and it centres its badge on a hashed CSS class, which collides with the
model chip when the model name is long. This plugin compares each candidate boundary
with the instant before it and only counts a real state flip, and its chip is an
ordinary flex child in the native statistics row.
- dsh-usage-monitor shows the
balance, but formats it as CNY whatever the API reports.
This plugin deliberately does not do cost or token accounting.
Install
From npm:
dsh plugin --profile web add dsh-billing-badge
or straight from the repository:
dsh plugin --profile web add github:devacc8/dsh-billing-badge
then restart dsh web. The package declares dsh.bundle.patch, so the host half is
reconciled into the profile's bundle list automatically.
Works on DeepSeek Harness 0.2.x, prereleases included, and on the 0.1.5 and 0.1.6 builds
that came before it. Older builds render the composer statistics as one labelled row and
the chip joins it; 0.1.6 moved those readings into the composer dock as pill buttons;
0.2.1 grouped them into activity and usage pills, and the chip follows the usage
group. The package declares engines.dsh with the range it supports, so the harness can
report a mismatch instead of loading the plugin silently.
Working on the plugin itself, install the checkout by path instead:
dsh plugin --profile web add link:/absolute/path/to/dsh-billing-badge
Security
A balance is a small surface, so it stays small:
- the API key is resolved in the host through the DSH credentials seam
(
ctx.credentials.resolve('DEEPSEEK_API_KEY'), environment fallback) and never
reaches the browser;
- the single route requires the
x-dsh-billing-badge: 1 header and rejects a
cross-origin Origin, so a cross-site page cannot reach it;
- nothing is written to disk, and no endpoint other than
api.deepseek.com is
contacted;
- a missing key, an HTTP error or a network failure all degrade to a state the panel
renders, never to a throw.
Development
The season logic lives in lib/season.js as a plain ESM module so it can be tested
directly. A browser bundle cannot import a sibling file (the loader resolves only
platform seeds, materialized packages and registered factories, and a self-subpath
require throws "missed the module table"), so scripts/inline-season.mjs copies the
module into lib/client.js between two markers with export stripped, and
test/client-sync.test.mjs fails if the copy drifts.
npm test # 30 tests: season rule, countdown invariant, host route, bundle
npm run sync # re-inline season.js into the bundle
npm run check # sync check plus a syntax check of both halves
The countdown has an invariant test rather than fixtures: every 13 minutes across nine
days, the reported target must be in the future, must change the season, and the
season must not change before it.
Layout
lib/season.js season rule, countdown, formatting (source of truth, tested)
lib/index.js host half: the balance route
lib/client.js browser half: the pill and its panel, with season.js inlined
cordis.patch.yml mounts the host half into the profile
scripts/ the inliner
test/ season, sync, host and bundle tests
GitHub Actions runs npm test and npm run check on Node 20 and 22.
MIT.
