opencode-usage-report 0.1.0 → 0.2.0

package/README.md

@@ -6,7 +6,8 @@
 
 An [opencode](https://opencode.ai) plugin that adds a `/usage` command (and a
 `usage_report` tool) showing the quota windows (5-hour, weekly, monthly) of your
-inference subscriptions — currently **Kimi Code** (`kimi-for-coding`) and
+inference subscriptions — currently **Kimi Code** (both regional plans:
+`kimi-code-plan-global` on kimi.ai and `kimi-code-plan-cn` on kimi.com) and
 **OpenCode Go** (`opencode-go`). It fetches from each provider's API, caches
 results on disk, and can fall back to a local estimate when the API is
 unreachable. It also emits background low-quota warnings in the TUI.
@@ -31,7 +32,7 @@ Add the plugin to `opencode.json` / `opencode.jsonc` and restart opencode:
 
 ```jsonc
 {
-  "plugin": ["./path/to/opencode-usage-report"] // or an npm spec
+  "plugin": ["opencode-usage-report"]
 }
 ```
 
@@ -41,20 +42,33 @@ options in the tuple form:
 
 ```jsonc
 {
-  "plugin": [["./path/to/opencode-usage-report", { "thresholdPercent": 75 }]]
+  "plugin": [["opencode-usage-report", { "thresholdPercent": 75 }]]
 }
 ```
 
 ### TUI sidebar panel
 
-Add the TUI module to `tui.json` and restart opencode:
+Add the plugin to `tui.json` and restart opencode:
 
 ```jsonc
 {
-  "plugin": ["file:///abs/path/to/opencode-usage-report/src/tui.tsx"]
+  "plugin": ["opencode-usage-report"]
 }
 ```
 
+Use the bare package name — opencode resolves the `./tui` entrypoint from the
+package `exports` on its own. (`opencode-usage-report/tui` is **not** a valid
+spec and will silently not load.)
+
+For local development, point the configs at the source instead:
+
+```jsonc
+// opencode.json
+{ "plugin": ["file:///abs/path/to/opencode-usage-report/src/index.ts"] }
+// tui.json
+{ "plugin": ["file:///abs/path/to/opencode-usage-report/src/tui.tsx"] }
+```
+
 The panel renders under opencode's native Context block in the session sidebar
 (order 150) and shows a colored progress bar per quota window, `NN%`, and a
 live reset countdown — refreshed every 60s, on `session.idle`, and on demand via
@@ -68,10 +82,13 @@ TUI options (tuple form): `providers`, `cacheTtlSeconds`, `thresholdPercent`,
 
 ## Commands
 
-- `/usage` — show every configured provider's quota windows.
-- `/usage kimi-for-coding` — filter to a single provider. The argument must match a
-  registered provider id **exactly** (`kimi-for-coding` or `opencode-go`); an
-  unknown id (e.g. `/usage kimi`) returns a helpful error listing the known ids.
+- `/usage` — show every configured provider's quota windows. Providers without a
+  resolved credential are skipped in this view.
+- `/usage kimi-code-plan-global` — filter to a single provider. The argument must
+  match a registered provider id **exactly** (`kimi-code-plan-global`,
+  `kimi-code-plan-cn` or `opencode-go`); an unknown id (e.g. `/usage kimi`)
+  returns a helpful error listing the known ids. An explicitly requested
+  provider with no credential is reported as an error row.
 - `/usage --json` — emit the raw `ProviderReport[]` JSON.
 - `/usage --refresh` — bypass the on-disk cache and fetch live.
 
@@ -103,7 +120,8 @@ per window until that window resets; it re-arms after usage drops below
 - Credential resolution order: `OPENCODE_USAGE_<ID>_KEY` env override, then
   `~/.local/share/opencode/auth.json` (`type: "api"` `.key`, or `type: "oauth"`
   `.access`). `$OPENCODE_DATA_HOME` overrides the data directory.
-- APIs: `https://api.kimi.com/coding/v1/usages` and
+- APIs: `https://api.kimi.ai/coding/v1/usages` (global plan),
+  `https://api.kimi.com/coding/v1/usages` (China plan) and
   `https://opencode.ai/zen/go/v1/usage` (custom `User-Agent` is required by the
   latter).
 - Cache and state live in `<data-home>/usage-report/` (TTL cache, session id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-usage-report",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "opencode plugin: /usage command showing subscription quota windows for configured providers",
   "author": "Kaan Chinar",
   "type": "module",

package/src/auth.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import type { Credential } from "./types.js";
 import { dataHome } from "./paths.js";
 
-/** "kimi-for-coding" -> "OPENCODE_USAGE_KIMI_FOR_CODING_KEY" (non-alphanumerics become "_", uppercased). */
+/** "kimi-code-plan-global" -> "OPENCODE_USAGE_KIMI_CODE_PLAN_GLOBAL_KEY" (non-alphanumerics become "_", uppercased). */
 export function envVarName(providerId: string): string {
   const normalized = providerId.replace(/[^a-zA-Z0-9]/g, "_").toUpperCase();
   return `OPENCODE_USAGE_${normalized}_KEY`;

package/src/index.ts

@@ -4,12 +4,14 @@ import { DEFAULT_OPTIONS, collectReports } from "./report.js";
 import { renderJson, renderText } from "./render.js";
 import { checkWarnings } from "./warn.js";
 import { toNumber } from "./normalize.js";
+import { adapters } from "./providers/index.js";
 import type { PluginOptions } from "./types.js";
 
 const WARN_THROTTLE_MS = 10 * 60 * 1000;
 
 const TOOL_DESCRIPTION =
-  "Show subscription usage/quota windows (5h, weekly, monthly) for configured inference providers (kimi-for-coding, opencode-go)";
+  "Show subscription usage/quota windows (5h, weekly, monthly) for configured inference providers " +
+  `(${adapters.map((adapter) => adapter.id).join(", ")})`;
 
 const COMMAND_TEMPLATE =
   "Call the usage_report tool with these arguments: $ARGUMENTS and present the result verbatim.";

package/src/providers/index.ts

@@ -1,5 +1,5 @@
 import type { ProviderAdapter } from "../types.js";
-import { kimiAdapter } from "./kimi.js";
+import { kimiCnAdapter, kimiGlobalAdapter } from "./kimi.js";
 import { opencodeGoAdapter } from "./opencode-go.js";
-export const adapters: ProviderAdapter[] = [kimiAdapter, opencodeGoAdapter];
+export const adapters: ProviderAdapter[] = [kimiGlobalAdapter, kimiCnAdapter, opencodeGoAdapter];
 export function getAdapter(id: string): ProviderAdapter | undefined { return adapters.find(a => a.id === id); }

package/src/providers/kimi.ts

@@ -9,11 +9,22 @@ import { AdapterError } from "../types.js";
 import { pick, ratioToPercent, toISODate, toNumber, windowFromCounts } from "../normalize.js";
 import { redact } from "../auth.js";
 
-const VERSION = "0.1.0";
-const ENDPOINT = "https://api.kimi.com/coding/v1/usages";
+const VERSION = "0.2.0";
+
+/**
+ * Kimi Code is split by region in opencode/models.dev: the global plan lives on
+ * api.kimi.ai and the mainland-China plan on api.kimi.com. Both expose the same
+ * `GET <base>/usages` contract, so one factory builds both adapters.
+ */
+export interface KimiAdapterConfig {
+  id: string;
+  displayName: string;
+  /** API base including the version segment, e.g. "https://api.kimi.ai/coding/v1". */
+  baseUrl: string;
+}
 
-function request(cred: Credential, opts: FetchOptions): Promise<Response> {
-  return fetch(ENDPOINT, {
+function request(cred: Credential, opts: FetchOptions, endpoint: string): Promise<Response> {
+  return fetch(endpoint, {
     method: "GET",
     headers: {
       Authorization: "Bearer " + cred.key,
@@ -25,11 +36,15 @@ function request(cred: Credential, opts: FetchOptions): Promise<Response> {
 }
 
 /** One retry on network throw or 5xx; 4xx and 2xx return immediately. */
-async function fetchWithRetry(cred: Credential, opts: FetchOptions): Promise<Response> {
+async function fetchWithRetry(
+  cred: Credential,
+  opts: FetchOptions,
+  endpoint: string,
+): Promise<Response> {
   let lastError: unknown = null;
   for (let attempt = 0; attempt < 2; attempt++) {
     try {
-      const res = await request(cred, opts);
+      const res = await request(cred, opts, endpoint);
       if (res.status >= 500) {
         lastError = new Error(`HTTP ${res.status}`);
         continue;
@@ -157,42 +172,59 @@ function parse(body: Record<string, unknown>, cred: Credential): AdapterResult {
   return { windows, extras };
 }
 
-export const kimiAdapter: ProviderAdapter = {
-  id: "kimi-for-coding",
-  displayName: "Kimi Code",
-  async fetch(cred: Credential, opts: FetchOptions): Promise<AdapterResult> {
-    const res = await fetchWithRetry(cred, opts);
+export function createKimiAdapter(config: KimiAdapterConfig): ProviderAdapter {
+  const endpoint = `${config.baseUrl}/usages`;
+  return {
+    id: config.id,
+    displayName: config.displayName,
+    async fetch(cred: Credential, opts: FetchOptions): Promise<AdapterResult> {
+      const res = await fetchWithRetry(cred, opts, endpoint);
 
-    if (res.status === 401) {
-      throw new AdapterError("auth", redact("invalid Kimi API key", cred.key));
-    }
-    if (res.status === 429) {
-      throw new AdapterError("rate-limited", redact("Kimi API rate limit exceeded", cred.key));
-    }
-    if (res.status < 200 || res.status >= 300) {
-      throw new AdapterError(
-        "bad-response",
-        redact(`Kimi API returned HTTP ${res.status}`, cred.key),
-      );
-    }
+      if (res.status === 401) {
+        throw new AdapterError("auth", redact("invalid Kimi API key", cred.key));
+      }
+      if (res.status === 429) {
+        throw new AdapterError("rate-limited", redact("Kimi API rate limit exceeded", cred.key));
+      }
+      if (res.status < 200 || res.status >= 300) {
+        throw new AdapterError(
+          "bad-response",
+          redact(`Kimi API returned HTTP ${res.status}`, cred.key),
+        );
+      }
 
-    let body: unknown;
-    try {
-      body = await res.json();
-    } catch {
-      throw new AdapterError(
-        "bad-response",
-        redact("Kimi API returned a non-JSON response", cred.key),
-      );
-    }
+      let body: unknown;
+      try {
+        body = await res.json();
+      } catch {
+        throw new AdapterError(
+          "bad-response",
+          redact("Kimi API returned a non-JSON response", cred.key),
+        );
+      }
 
-    if (body === null || typeof body !== "object" || Array.isArray(body)) {
-      throw new AdapterError(
-        "bad-response",
-        redact("Kimi API returned an unexpected response shape", cred.key),
-      );
-    }
+      if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        throw new AdapterError(
+          "bad-response",
+          redact("Kimi API returned an unexpected response shape", cred.key),
+        );
+      }
+
+      return parse(body as Record<string, unknown>, cred);
+    },
+  };
+}
 
-    return parse(body as Record<string, unknown>, cred);
-  },
-};
+/** Kimi For Coding (kimi.ai) — the global `kimi-code-plan-global` provider. */
+export const kimiGlobalAdapter: ProviderAdapter = createKimiAdapter({
+  id: "kimi-code-plan-global",
+  displayName: "Kimi Code (kimi.ai)",
+  baseUrl: "https://api.kimi.ai/coding/v1",
+});
+
+/** Kimi For Coding (kimi.com) — the mainland-China `kimi-code-plan-cn` provider. */
+export const kimiCnAdapter: ProviderAdapter = createKimiAdapter({
+  id: "kimi-code-plan-cn",
+  displayName: "Kimi Code (kimi.com)",
+  baseUrl: "https://api.kimi.com/coding/v1",
+});

package/src/providers/opencode-go.ts

@@ -11,7 +11,7 @@ import { AdapterError } from "../types.js";
 import { toISODate, toNumber } from "../normalize.js";
 import { redact } from "../auth.js";
 
-const VERSION = "0.1.0";
+const VERSION = "0.2.0";
 const USER_AGENT = "opencode-usage-report/" + VERSION;
 const ENDPOINT = "https://opencode.ai/zen/go/v1/usage";
 

package/src/report.ts

@@ -69,9 +69,14 @@ async function collectOne(
   options: PluginOptions,
   refresh: boolean,
   env: NodeJS.ProcessEnv,
-): Promise<ProviderReport> {
+  explicit: boolean,
+): Promise<ProviderReport | null> {
   const cred = resolveCredential(id, { env });
-  if (cred === null) return errorReport(id, adapter.displayName, "no credential found");
+  if (cred === null) {
+    // The default view lists only providers that are actually configured; a
+    // provider the user asked for by name still reports the missing credential.
+    return explicit ? errorReport(id, adapter.displayName, "no credential found") : null;
+  }
 
   if (!refresh) {
     const cached = await readCache(id, options.cacheTtlSeconds, env);
@@ -126,8 +131,9 @@ async function collectOne(
 
 /**
  * Collects normalized usage reports for the requested providers (default: every
- * registered adapter). Never throws: each provider is isolated and failures
- * surface as `source: "error"` rows.
+ * configured adapter; unconfigured ones are skipped unless requested by name).
+ * Never throws: each provider is isolated and failures surface as
+ * `source: "error"` rows.
  */
 export async function collectReports(opts: CollectReportsOptions = {}): Promise<ProviderReport[]> {
   const options: PluginOptions = { ...DEFAULT_OPTIONS, ...(opts.options ?? {}) };
@@ -135,10 +141,9 @@ export async function collectReports(opts: CollectReportsOptions = {}): Promise<
   const refresh = opts.refresh === true;
 
   // An empty filter is treated like "no filter": report every registered adapter.
-  const ids =
-    firstNonEmpty(opts.providers) ??
-    firstNonEmpty(options.providers) ??
-    adapters.map((adapter) => adapter.id);
+  const requested = firstNonEmpty(opts.providers) ?? firstNonEmpty(options.providers);
+  const ids = requested ?? adapters.map((adapter) => adapter.id);
+  const explicit = requested !== null;
   const reports: ProviderReport[] = [];
 
   for (const id of ids) {
@@ -150,7 +155,8 @@ export async function collectReports(opts: CollectReportsOptions = {}): Promise<
     }
 
     try {
-      reports.push(await collectOne(id, adapter, options, refresh, env));
+      const report = await collectOne(id, adapter, options, refresh, env, explicit);
+      if (report !== null) reports.push(report);
     } catch {
       // Last-resort isolation: never let one provider break the whole report.
       reports.push(errorReport(id, adapter.displayName, "internal error while collecting usage"));

package/src/tui-format.ts

@@ -109,10 +109,10 @@ export function percentText(w: {
   const usedIsNumber = typeof used === "number" && Number.isFinite(used);
   const limitIsNumber = typeof limit === "number" && Number.isFinite(limit);
   if (usedIsNumber && limitIsNumber) {
-    return `${used.toLocaleString()}/${limit.toLocaleString()}`;
+    return `${used.toLocaleString("en-US")}/${limit.toLocaleString("en-US")}`;
   }
   if (usedIsNumber) {
-    return `~${used.toLocaleString()}`;
+    return `~${used.toLocaleString("en-US")}`;
   }
   return "—";
 }