@vibe-cafe/vibe-usage 0.13.0 → 0.13.1

package/README.md

@@ -62,6 +62,7 @@ npx @vibe-cafe/vibe-usage help --all   # Full help (plain `help` shows the short
 
 The versioned `quota` JSON contract is designed for local desktop clients. `discover` only checks ordinary app, config-directory, and executable presence signals: it does not open credentials or use the network. `fetch` invokes only products explicitly named with `--product`, and one provider failure does not prevent results for the others.
 
+- A quota result may carry a machine-readable `emptyReason` (`limitReached` / `noWindow` / `notEntitled` / `sessionWithoutPlanLimits`) alongside the human `message`; it is additive within schema v1, so clients that do not know it ignore it, and it says *why* there was no window instead of leaving the caller to parse prose. OpenCode Go sets `notEntitled` for a key without the Go subscription.
 - **Kimi Code** reads the official OAuth file from `$KIMI_CODE_HOME/credentials/kimi-code.json` (otherwise `~/.kimi-code/credentials/kimi-code.json`) and falls back to the legacy `$KIMI_SHARE_DIR` / `~/.kimi` location — the first login that exists wins. It calls `https://api.kimi.com/coding/v1/usages` and supports both the current 2.x response and the legacy quota response. When the short-lived access token is close to expiry, it uses Kimi's standard OAuth refresh flow and atomically rotates the official credential with owner-only permissions. Refreshes are serialized across Vibe Usage processes and re-check the file before writing so a concurrent Kimi CLI refresh wins safely.
 - **ZCode / GLM Coding Plan** accepts only a caller-supplied regional key: `BIGMODEL_API_KEY` calls the domestic `https://open.bigmodel.cn/api/monitor/usage/quota/limit`, while the existing `Z_AI_API_KEY` keeps using `https://api.z.ai/api/monitor/usage/quota/limit`. If both are present, the explicitly named BigModel key wins. It does not read ZCode's private OAuth state.
 - **Grok** reads at most the final 2 MiB of the official CLI's ordinary `$GROK_HOME/logs/unified.jsonl` (default `~/.grok/logs/unified.jsonl`). It accepts only the structured `billing: fetched credits config` event and projects the current utilization, period bounds, subscription tier, and event timestamp. It performs no network request, reads no credentials, and never returns or retains other log fields.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-cafe/vibe-usage",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "Track your AI coding tool token usage and sync to vibecafe.ai",
   "type": "module",
   "scripts": {

package/src/quotas/providers/opencode-go.js

@@ -184,10 +184,13 @@ export async function fetchOpenCodeGoQuota({
       }), token);
     }
     if (response.status === 403) {
-      // A valid OpenCode key without an active Go subscription.
+      // A valid OpenCode key without an active Go subscription. The reason
+      // travels machine-readably so a client can say "not subscribed" instead
+      // of showing a neutral empty state.
       return attachCacheScope(quotaResult({
         id: PRODUCT_ID,
         status: 'no_data',
+        emptyReason: 'notEntitled',
         message: 'OpenCode Go subscription is not active',
         fetchedAt: now,
       }), token);

package/src/quotas/schema.js

@@ -15,6 +15,19 @@ export const FETCHABLE_QUOTA_PRODUCT_IDS = Object.freeze([
   'opencode-go',
 ]);
 
+/**
+ * Machine-readable "why there was no window" values, shared with the desktop
+ * clients' `EmptyReason` (macOS `RateLimit.swift`) and additive within schema
+ * v1: a client that does not know the field ignores it, and a client that does
+ * can render the reason instead of a neutral empty state.
+ */
+export const QUOTA_EMPTY_REASONS = Object.freeze([
+  'limitReached',
+  'noWindow',
+  'notEntitled',
+  'sessionWithoutPlanLimits',
+]);
+
 const FETCH_STATUSES = new Set([
   'ok',
   'no_data',
@@ -129,6 +142,7 @@ export function quotaResult({
   dataAsOf = fetchedAt,
   message,
   source = 'live',
+  emptyReason,
 }) {
   if (!FETCHABLE_QUOTA_PRODUCT_IDS.includes(id)) {
     throw new TypeError(`unsupported quota product: ${id}`);
@@ -147,6 +161,12 @@ export function quotaResult({
   if (normalizedDataAsOf) result.dataAsOf = normalizedDataAsOf;
   if (typeof planLabel === 'string' && planLabel.trim()) result.planLabel = planLabel.trim();
   if (typeof message === 'string' && message.trim()) result.message = message.trim();
+  if (emptyReason !== undefined && emptyReason !== null) {
+    if (!QUOTA_EMPTY_REASONS.includes(emptyReason)) {
+      throw new TypeError(`invalid quota emptyReason: ${emptyReason}`);
+    }
+    result.emptyReason = emptyReason;
+  }
   return result;
 }