@hk_net/pi-usage-bars 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## Unreleased
+
+## [0.4.1] - 2026-07-31
+
+### Fixed
+
+- Classify Codex quota windows by `limit_window_seconds` instead of assuming `primary_window` is always the session limit. Codex accounts that expose only a seven-day primary window now show it as Weekly and no longer display a fabricated `Session 0%` lane.
+
+### Changed
+
+- Updated the development and test baseline to Pi SDK 0.83.0 while retaining runtime compatibility with Pi 0.81.1 and newer.
+
+## [0.4.0] - 2026-07-22
+
+### Added
+
+- Added Kimi For Coding quota support through Pi's `kimi-coding` credential and the first-party five-hour/weekly usage endpoint.
+- Added separate MiniMax Global and China Coding/Token Plan support, including the current token-plan endpoint and legacy coding-plan fallback.
+- Added provider-specific quota labels and support for MiniMax responses that expose an interval quota without a weekly quota.
+- Added neutral MiniMax purchased-Credits balance rendering when a key-authenticated first-party response exposes a balance.
+- Added OpenRouter account balance and daily/weekly/monthly key spend using the first-party Credits and Key APIs.
+- Added OpenRouter per-key limit bars only when the key has a real configured credit limit.
+- Added DeepSeek total, topped-up, and granted balance support through the official key-authenticated balance API.
+- Added separate Moonshot/Kimi API Global and China available, cash, and voucher balance support.
+- Added a typed financial-metrics roadmap for further balance/spend providers.
+- Added provider parsing, regional routing, endpoint fallback, financial rendering, authentication lifecycle, and smoke tests.
+- Added CI, reproducible installs, production auditing, and a maintainer release guide.
+
+### Changed
+
+- Treat MiniMax status `2062` as a neutral “No active Token Plan” account state rather than an API error; the cookie-only console balance endpoint remains out of scope.
+- Expanded endpoint configuration documentation for Kimi, MiniMax, OpenRouter, DeepSeek, and Moonshot.
+- Changed npm publishing to an explicit manual workflow so source tags cannot accidentally republish an already released version.
+- Bumped the package version to 0.4.0.
+
 ## [0.3.0] - 2026-07-22
 
 ### Breaking changes

package/README.md

@@ -1,13 +1,13 @@
 # pi-usage-bars
 
-Subscription usage indicators for [Pi](https://github.com/earendil-works/pi).
+Quota, balance, and spend indicators for [Pi](https://github.com/earendil-works/pi).
 
 ![Codex footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/codex.png)
 
 It adds:
 
-- a footer status bar for the active subscription provider
-- a `/usage` command showing every configured supported subscription
+- a footer status bar for the active supported provider
+- a `/usage` command showing configured quota, balance, and spend data
 
 ## Supported providers
 
@@ -17,6 +17,19 @@ It adds:
 | Anthropic Claude | `anthropic` | Claude Pro/Max OAuth |
 | ZAI Coding Plan (Global) | `zai` | ZAI API key |
 | ZAI Coding Plan (China) | `zai-coding-cn` | ZAI China API key |
+| Kimi For Coding | `kimi-coding` | Kimi Coding Plan API key |
+| MiniMax Coding Plan (Global) | `minimax` | MiniMax Global API key |
+| MiniMax Coding Plan (China) | `minimax-cn` | MiniMax China API key |
+| OpenRouter | `openrouter` | OpenRouter API key |
+| DeepSeek | `deepseek` | DeepSeek API key |
+| Moonshot/Kimi API (Global) | `moonshotai` | Moonshot Global API key |
+| Moonshot/Kimi API (China) | `moonshotai-cn` | Moonshot China API key |
+
+DeepSeek shows total, topped-up, and granted balances in the currency returned by the API. Moonshot shows available, cash, and voucher balances; this is separate from the Kimi For Coding subscription provider. Pi uses `MOONSHOT_API_KEY` for both Moonshot regions, so `/usage` automatically hides the expected authentication failure from the region where a shared environment key is not valid.
+
+OpenRouter shows the account credit balance and current daily, weekly, and monthly key spend. If the API key has a configured credit limit, that limit is also rendered as a usage bar.
+
+MiniMax Subscription Keys can represent an active Token Plan, purchased Credits, or both. The extension shows quota windows when present and a neutral credit-balance line if a first-party key-authenticated response exposes `points_balance`/`credits_balance`. MiniMax currently exposes Credits-only balances through a console endpoint requiring browser-cookie authentication, so a key-only Credits account is shown as “No active Token Plan” with a direction to check the console rather than a fabricated percentage. The extension does not import browser cookies.
 
 Google Gemini CLI and Google Antigravity are not supported because Pi removed those built-in providers in version 0.71.0.
 
@@ -43,11 +56,17 @@ pi install https://github.com/hknet/pi-usage-bars
 
 Restart Pi after installation, or use `/reload` when the package is already installed.
 
+Update an existing npm installation with:
+
+```bash
+pi update npm:@hk_net/pi-usage-bars
+```
+
 ## Use
 
 ### Footer usage bars
 
-When the active model belongs to a configured supported provider, the footer shows session and weekly usage with reset countdowns when available.
+When the active model belongs to a configured supported provider, the footer shows its available quota windows with reset countdowns when provided by the service.
 
 ![Claude footer bar](https://raw.githubusercontent.com/hknet/pi-usage-bars/main/assets/claude.png)
 
@@ -61,17 +80,31 @@ Run `/usage` to open a searchable list of configured supported providers.
 
 ## Endpoint configuration
 
-The ZAI monitoring endpoints can be overridden:
+First-party monitoring endpoints can be overridden:
 
 | Variable | Default |
 | --- | --- |
 | `PI_ZAI_USAGE_ENDPOINT` | `https://api.z.ai/api/monitor/usage/quota/limit` |
 | `PI_ZAI_CODING_CN_USAGE_ENDPOINT` | `https://open.bigmodel.cn/api/monitor/usage/quota/limit` |
+| `PI_KIMI_USAGE_ENDPOINT` | `https://api.kimi.com/coding/v1/usages` |
+| `PI_MINIMAX_USAGE_ENDPOINT` | `https://api.minimax.io/v1/token_plan/remains` |
+| `PI_MINIMAX_LEGACY_USAGE_ENDPOINT` | `https://api.minimax.io/v1/api/openplatform/coding_plan/remains` |
+| `PI_MINIMAX_CN_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/token_plan/remains` |
+| `PI_MINIMAX_CN_LEGACY_USAGE_ENDPOINT` | `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` |
+| `PI_OPENROUTER_CREDITS_ENDPOINT` | `https://openrouter.ai/api/v1/credits` |
+| `PI_OPENROUTER_KEY_ENDPOINT` | `https://openrouter.ai/api/v1/key` |
+| `PI_DEEPSEEK_BALANCE_ENDPOINT` | `https://api.deepseek.com/user/balance` |
+| `PI_MOONSHOT_BALANCE_ENDPOINT` | `https://api.moonshot.ai/v1/users/me/balance` |
+| `PI_MOONSHOT_CN_BALANCE_ENDPOINT` | `https://api.moonshot.cn/v1/users/me/balance` |
 
 **Security:** the corresponding provider token is sent as a bearer token to the configured endpoint. Only override these variables with an endpoint you trust.
 
 The Codex and Claude usage endpoints are fixed to their first-party services. Claude responses are cached briefly in the system temporary directory to coordinate multiple Pi processes and reduce rate limiting. The cache contains usage values, not credentials.
 
+## Financial metrics roadmap
+
+Quota percentages and monetary account data have different meaning and color semantics. OpenRouter, DeepSeek, Moonshot, and MiniMax financial data are rendered as neutral account values; percentages are used only when an actual limit exists. See [Financial metrics plan](docs/financial-metrics-plan.md) for the normalized model and future provider rollout.
+
 ## Development
 
 Install Node.js 22.19+ and Bun 1.3, then run:
@@ -83,9 +116,12 @@ npm run check
 
 `npm run check` performs a strict TypeScript check, runs the Bun test suite, and smoke-loads the extension with the pinned current Pi release.
 
+Maintainers should follow the complete [release and npm publication guide](docs/releasing.md). npm publication is manual; pushing a Git tag does not publish automatically.
+
 ## Credits
 
 This extension is based on and inspired by:
 
 - [CodexBar](https://github.com/steipete/CodexBar)
 - [rho usage-bars](https://github.com/mikeyobrien/rho/tree/main/extensions/usage-bars)
+- [ajarellanod/pi-usage-bars](https://github.com/ajarellanod/pi-usage-bars)

package/docs/financial-metrics-plan.md

@@ -0,0 +1,75 @@
+# Financial metrics plan
+
+## Goal
+
+Add an optional account-value view without treating balances and spend as subscription quota. Quota usage increases toward exhaustion; a balance decreases toward exhaustion; spend may be meaningful only relative to a budget. Those metrics must retain distinct labels and color rules.
+
+## Normalized model
+
+A future core revision should replace the two fixed quota fields with a list of typed metrics:
+
+```ts
+type UsageMetric =
+  | {
+      kind: "quota";
+      id: string;
+      label: string;
+      usedPercent: number;
+      resetsAt?: string;
+    }
+  | {
+      kind: "money";
+      id: string;
+      label: string;
+      currency: string;
+      balance?: number;
+      spent?: number;
+      limit?: number;
+      period?: "day" | "week" | "month" | "lifetime";
+      resetsAt?: string;
+    };
+```
+
+Provider fetchers should return normalized metrics. Rendering, not provider parsing, decides which metrics appear in the footer or `/usage` dialog.
+
+## View behavior
+
+The initial OpenRouter implementation displays both balance and spend in `/usage`. The footer prefers the balance and current-month spend, while a configured per-key limit remains the primary bar. A later persistent view setting may provide:
+
+- `auto`: prefer quota windows; otherwise show a financial summary.
+- `balance`: show remaining prepaid/credit balance.
+- `spent`: show spend and a percentage only when a real limit or budget exists.
+- `off`: retain quota-only behavior.
+
+No environment variable or config key is reserved for that future view selector yet.
+
+Color semantics:
+
+- quota `usedPercent`: high is bad;
+- balance: low remaining balance is bad only when a known starting balance or warning threshold exists;
+- spend/limit: high is bad;
+- unconstrained spend and raw balance: neutral colors, never a manufactured percentage.
+
+## Provider rollout
+
+1. **OpenRouter — implemented in 0.4.0**
+   - `GET /api/v1/credits`: purchased credits, total usage, derived balance.
+   - `GET /api/v1/key`: configured key limit and daily/weekly/monthly spend where supplied.
+   - Uses only the API key resolved through Pi's provider registry.
+2. **Balance providers**
+   - DeepSeek and Moonshot/Kimi API prepaid balances are implemented in 0.4.0 using their official key-authenticated endpoints.
+   - Mistral balance or monthly-plan data when available through an API credential.
+   - MiniMax purchased Credits have a limited provider-specific implementation: when a first-party key-authenticated quota response includes `points_balance` or `credits_balance`, it is rendered neutrally. In current MiniMax deployments, the dedicated `/backend/account/token_plan_credit` endpoint requires browser-cookie authentication and does not accept the Subscription Key, so it remains out of scope. API status `2062` is rendered as a neutral “No active Token Plan” account state and never converted into a quota percentage.
+3. **Spend providers**
+   - OpenAI organization spend requires an Admin API key and therefore should appear only when Pi can resolve an appropriate credential.
+   - AWS Bedrock spend requires explicit Cost Explorer permissions and should remain a separate opt-in integration.
+
+Browser cookies and direct reads of Pi's credential files remain out of scope.
+
+## Migration steps
+
+1. Introduce `UsageMetric` alongside the existing `session`/`weekly` compatibility fields.
+2. Convert quota fetchers and both renderers to metric lists.
+3. Add persistent view selection; neutral financial formatting is already covered by OpenRouter tests.
+4. Add further key-authenticated financial providers beyond OpenRouter, DeepSeek, and Moonshot.
+5. Remove compatibility fields only in a documented major release.

package/docs/releasing.md

@@ -0,0 +1,84 @@
+# Releasing
+
+This repository uses semantic versions. The package version, changelog heading, Git tag, and npm version must agree.
+
+Local publication uses npm browser authentication. The GitHub Actions publish workflow is manual-only; pushing a tag does not publish the package.
+
+## Prerequisites
+
+- Write access to `hknet/pi-usage-bars`.
+- Publish access to the npm scope `@hk_net`.
+- Node.js 22.19 or newer.
+- A clean, synchronized `main` branch.
+
+Never place an npm token in the repository, command history, or endpoint configuration. Complete npm's browser or OTP authorization when prompted.
+
+## Recommended release script
+
+From the repository root, provide the exact new semantic version:
+
+```bash
+cd /path/to/pi-usage-bars
+scripts/release.sh 0.4.1
+```
+
+This **default command only prepares the release**. It deliberately stops before npm login or publication, so the pushed release commit can be reviewed first. The launcher first executes an immutable temporary copy of itself, so editing the script while a release is running cannot corrupt that run.
+
+Preparation:
+
+1. verifies that `main` is clean and synchronized with `origin/main`;
+2. rejects an existing npm version or Git tag;
+3. updates `package.json` and `package-lock.json` without creating an early tag;
+4. promotes the `Unreleased` changelog entries into a dated release while preserving an empty `Unreleased` heading;
+5. installs dependencies with `npm ci --no-audit`, provisions a temporary pinned Bun binary, and runs typecheck, tests, detailed dependency audits, and package dry-run; and
+6. commits and pushes the release source.
+
+After reviewing the prepared commit, stage it for browser approval:
+
+```bash
+scripts/release.sh 0.4.1 stage
+```
+
+`stage` submits the package to npm's staged-publishing queue. It **does not publish live**, does not open a browser, and does not tag Git. If npm authentication is needed, run `npm login --auth-type=web` manually first.
+
+In [npmjs.com](https://www.npmjs.com), open **Staged Packages**, review the staged tarball, and click **Approve**. npm prompts for 2FA during approval. After npm shows the version as live, finalize the release:
+
+```bash
+scripts/release.sh 0.4.1 finalize
+```
+
+`finalize` refuses to run until the exact version is live in the npm registry. It then verifies registry metadata and creates/pushes the annotated Git tag. It never stages or publishes a package.
+
+Use `--yes` only for attended preparation:
+
+```bash
+scripts/release.sh 0.4.1 --yes  # prepare only
+```
+
+## Recovery
+
+Staging and finalization are safe to rerun: `stage` refuses if the exact version is already live, and `finalize` refuses until it is live. Never force-push a release tag.
+
+The release script first prints a full dependency audit with package names, dependency paths, affected ranges, and available fixes. This is informational because it includes development-only dependencies. It then runs a blocking production-only audit, which rejects high or critical production findings.
+
+Show script help with:
+
+```bash
+scripts/release.sh --help
+```
+
+## Post-release verification
+
+Confirm installation through Pi:
+
+```bash
+pi install npm:@hk_net/pi-usage-bars
+# If already installed from npm:
+pi update npm:@hk_net/pi-usage-bars
+```
+
+Restart Pi, or use `/reload`, then run `/usage`.
+
+## GitHub Actions alternative
+
+The **Publish to npm (manual)** workflow is available as an alternative. It requires the `NPM_TOKEN` repository secret and publishes with npm provenance. Do not run it after publishing the same version locally.