Show real credit spend and a per-model breakdown under the balance: - ``src/usage.ts`` (new, pure): idempotent day buckets keyed by message id, day/month totals, retention pruning, validated KV serialization. - Real spend = delta of ``x-credits-remaining`` between two free probes (top-ups are not counted as spend), covering every client of the key. - Per-model detail = reconciliation of local GreenPT assistant messages (tokens + estimated cost, marked ``~``), re-run on every refresh and on ``session.idle``; last 10 sessions backfilled at startup. - Buckets persisted in the plugin KV store (90-day window) with new options ``trackUsage``, ``usageWindowDays``, ``usageBackfill`` and a ``greenpt.usage.reset`` command.
123 lines
5.1 KiB
Markdown
123 lines
5.1 KiB
Markdown
# opencode-greenpt-usage
|
|
|
|
An [OpenCode](https://opencode.ai) TUI plugin that shows the remaining
|
|
**GreenPT API credit balance** and the **consumption** of the API key
|
|
(real credit spend plus a per-model breakdown) in the sidebar.
|
|
|
|
```
|
|
▼ GreenPT
|
|
Balance 5.31 € updated 21:35
|
|
Spent today 0.04 € month 0.31 €
|
|
glm-5.3-flash 12.4k tok ~0.02 €
|
|
kimi-k2 3.1k tok ~0.01 €
|
|
```
|
|
|
|
## How it works
|
|
|
|
- The API key is resolved in this order:
|
|
1. the plugin `apiKey` option;
|
|
2. the `GREENPT_API_KEY` environment variable;
|
|
3. the **active** OpenCode auth store (`auth.json`, provider `greenpt`,
|
|
entry `type: "api"`) — i.e. exactly what a plain `opencode auth login`
|
|
produces.
|
|
- The balance is read with a **free** `HEAD /v1/chat/completions` probe:
|
|
the API answers `400 Bad Request` before any billing, yet the response
|
|
still carries the `x-credits-remaining` header. No credit is consumed
|
|
and no generation is triggered.
|
|
- **Usage tracking** keeps per-day buckets, persisted in the plugin KV
|
|
store (90 days by default):
|
|
- *real credit spend* is observed as the drop of `x-credits-remaining`
|
|
between two balance probes — this covers **every client** of the API
|
|
key, not just OpenCode, but has no per-model detail;
|
|
- *per-model breakdown* (tokens and estimated cost) is reconciled from
|
|
the GreenPT assistant messages of your local OpenCode sessions — this
|
|
detail is therefore **local to this machine** and priced with
|
|
OpenCode's model catalog, which may differ from GreenPT's credit
|
|
pricing (estimates are marked with `~`).
|
|
- At startup, the last 10 sessions are reconciled to backfill recent
|
|
history; counters can be cleared with `greenpt.usage.reset`.
|
|
- The section is **hidden while no GreenPT key is present**.
|
|
- Refresh happens on startup, at the end of a session, on server
|
|
reconnection, on a timer (300 s by default) and on demand through the
|
|
`greenpt.refresh` command; usage buckets are reconciled on each refresh
|
|
and at the end of each session.
|
|
|
|
There is no dependency on any local profile or command: the plugin only
|
|
looks for a key.
|
|
|
|
## Requirements
|
|
|
|
- OpenCode `>= 1.18.0` (TUI plugin system).
|
|
- A GreenPT account and API key.
|
|
|
|
## Installation
|
|
|
|
1. **Clone this repository** wherever you keep your projects.
|
|
|
|
2. **Connect GreenPT to OpenCode**:
|
|
|
|
```bash
|
|
opencode auth login
|
|
```
|
|
|
|
Pick **GreenPT** from the list, then paste the API key.
|
|
|
|
(Alternative: export `GREENPT_API_KEY` in your environment.)
|
|
|
|
3. **Register the plugin** in `~/.config/opencode/tui.json`, setting the
|
|
**absolute path to your clone**:
|
|
|
|
```jsonc
|
|
{
|
|
"$schema": "https://opencode.ai/tui.json",
|
|
"plugin": [
|
|
["file:///ABSOLUTE/PATH/TO/opencode-greenpt-usage/src/index.tsx", { "order": 700 }]
|
|
]
|
|
}
|
|
```
|
|
|
|
> Use a `file://` URL pointing at the source file `src/index.tsx`
|
|
> (OpenCode compiles the TSX itself). Do not point at a bundle: that
|
|
> would embed a second copy of `solid-js` and the section would stay
|
|
> blank.
|
|
|
|
4. **Fully quit OpenCode and relaunch it** (plugins are not hot-reloaded).
|
|
|
|
## Configuration
|
|
|
|
All options are optional and go in the plugin entry of `tui.json`:
|
|
|
|
| Option | Type | Default | Description |
|
|
| --------------------- | ------- | --------------------------- | ------------------------------------------------------- |
|
|
| `apiKey` | string | resolved automatically | Explicit GreenPT key. |
|
|
| `baseUrl` | string | `https://api.greenpt.ai/v1` | GreenPT API base URL. |
|
|
| `refreshInterval` | number | `300` | Refresh interval in seconds (`0` disables the timer). |
|
|
| `order` | number | `700` | Sidebar section position. |
|
|
| `showWhenUnavailable` | boolean | `false` | Show a hint when no GreenPT key exists. |
|
|
| `unit` | string | `€` | Unit appended after the amount. |
|
|
| `trackUsage` | boolean | `true` | Track credit spend and per-model usage. |
|
|
| `usageWindowDays` | number | `90` | Retention window for per-day usage buckets. |
|
|
| `usageBackfill` | number | `10` | Recent sessions reconciled at startup (`0` disables). |
|
|
|
|
## Troubleshooting
|
|
|
|
- **The section does not appear**: make sure `opencode auth login` stored a
|
|
`greenpt` key (or that `GREENPT_API_KEY` is set), and that the `file://`
|
|
URL in `tui.json` points at the right path.
|
|
- **"invalid GreenPT key"**: the API key was rejected (HTTP 401).
|
|
- **"balance unavailable"**: GreenPT did not return the balance header; try
|
|
again later.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm install
|
|
npm test # unit tests
|
|
npm run typecheck # type check
|
|
GREENPT_API_KEY=... npm run test:integration # test against the live API
|
|
```
|
|
|
|
## License
|
|
|
|
AGPL-3.0-or-later. See [LICENSE](LICENSE).
|