ccusage 0.1.6__tar.gz → 0.1.8__tar.gz

{ccusage-0.1.6 → ccusage-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ccusage
-Version: 0.1.6
+Version: 0.1.8
 Summary: Claude Code usage monitor — fetches rate limits from Anthropic's API
 Project-URL: Homepage, https://github.com/wakamex/ccusage
 Project-URL: Source, https://github.com/wakamex/ccusage
@@ -94,6 +94,15 @@ Claude Code gets rate limit data from two places:
 | `seven_day_opus` | `seven_day_opus` | Rolling 7-day Opus-specific window |
 | `overage` | `extra_usage` | Extra/overage usage (if enabled) |
 
+The flat `seven_day_*` keys above are all `null` now — the live quota data
+lives in a structured `limits` array, which ccusage reads. Each entry is
+self-describing: `kind` (`session` / `weekly_all` / `weekly_scoped`),
+`percent`, `resets_at`, and for scoped limits a `scope.model.display_name`.
+Model-scoped weekly windows (Opus, Sonnet, and a newly added **Fable**) are
+keyed by their model name, so any new one is auto-detected and displayed with
+no code change (e.g. `scope.model.display_name: "Fable"` → "Week (Fable)",
+statusline `fab:`).
+
 ### API response format
 
 ```
@@ -145,7 +154,7 @@ The OAuth token lives at `~/.claude/.credentials.json`:
 }
 ```
 
-The access token expires roughly hourly. Claude Code refreshes it automatically — as long as you have an active Claude Code session, the token stays valid for ccusage to read.
+The access token expires roughly hourly. When it's expired (or rejected with a 401/403), ccusage refreshes it itself using the `refreshToken` and writes the rotated credentials back to `.credentials.json` — the same flow Claude Code uses, so the two stay in sync and no active Claude Code session is needed.
 
 ### Warning thresholds (from cli.js)
 

{ccusage-0.1.6 → ccusage-0.1.8}/README.md

@@ -85,6 +85,15 @@ Claude Code gets rate limit data from two places:
 | `seven_day_opus` | `seven_day_opus` | Rolling 7-day Opus-specific window |
 | `overage` | `extra_usage` | Extra/overage usage (if enabled) |
 
+The flat `seven_day_*` keys above are all `null` now — the live quota data
+lives in a structured `limits` array, which ccusage reads. Each entry is
+self-describing: `kind` (`session` / `weekly_all` / `weekly_scoped`),
+`percent`, `resets_at`, and for scoped limits a `scope.model.display_name`.
+Model-scoped weekly windows (Opus, Sonnet, and a newly added **Fable**) are
+keyed by their model name, so any new one is auto-detected and displayed with
+no code change (e.g. `scope.model.display_name: "Fable"` → "Week (Fable)",
+statusline `fab:`).
+
 ### API response format
 
 ```
@@ -136,7 +145,7 @@ The OAuth token lives at `~/.claude/.credentials.json`:
 }
 ```
 
-The access token expires roughly hourly. Claude Code refreshes it automatically — as long as you have an active Claude Code session, the token stays valid for ccusage to read.
+The access token expires roughly hourly. When it's expired (or rejected with a 401/403), ccusage refreshes it itself using the `refreshToken` and writes the rotated credentials back to `.credentials.json` — the same flow Claude Code uses, so the two stay in sync and no active Claude Code session is needed.
 
 ### Warning thresholds (from cli.js)
 

{ccusage-0.1.6 → ccusage-0.1.8}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ccusage"
-version = "0.1.6"
+version = "0.1.8"
 description = "Claude Code usage monitor — fetches rate limits from Anthropic's API"
 readme = "README.md"
 requires-python = ">=3.12"

{ccusage-0.1.6 → ccusage-0.1.8}/src/ccusage/__init__.py

@@ -15,10 +15,12 @@ Usage:
 
 import argparse
 import json
+import os
 import signal
 import subprocess
 import sys
 import time
+import urllib.error
 import urllib.request
 from datetime import datetime, timezone
 from pathlib import Path
@@ -69,6 +71,8 @@ CLAUDE_DIR = Path.home() / ".claude"
 CREDENTIALS_FILE = _resolve_claude_path(".credentials.json")
 USAGE_FILE = _resolve_claude_path("usage-limits.json")
 DAEMON_INTERVAL = 300  # 5 minutes
+TOKEN_URL = "https://console.anthropic.com/v1/oauth/token"
+CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e"  # Claude Code's public OAuth client
 
 
 def get_credentials() -> dict | None:
@@ -90,10 +94,59 @@ def get_plan(creds: dict | None = None) -> str:
     return tier.removeprefix("default_claude_")
 
 
+def refresh_credentials(creds: dict) -> dict:
+    """Refresh the OAuth access token and persist updated credentials.
+
+    Anthropic rotates refresh tokens, so the new refreshToken MUST be written
+    back to .credentials.json or Claude Code's stored one goes stale and the
+    user gets logged out.
+    """
+    oauth = creds.get("claudeAiOauth", {})
+    refresh_token = oauth.get("refreshToken")
+    if not refresh_token:
+        raise RuntimeError("OAuth token expired and no refresh token — open Claude Code to log in")
+
+    payload = json.dumps({
+        "grant_type": "refresh_token",
+        "refresh_token": refresh_token,
+        "client_id": CLIENT_ID,
+    }).encode()
+    req = urllib.request.Request(
+        TOKEN_URL,
+        data=payload,
+        headers={"Content-Type": "application/json"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            result = json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(f"Token refresh failed ({e.code}) — open Claude Code to refresh it") from e
+
+    oauth = dict(oauth)
+    oauth["accessToken"] = result["access_token"]
+    if result.get("refresh_token"):
+        oauth["refreshToken"] = result["refresh_token"]
+    oauth["expiresAt"] = int(time.time() * 1000 + int(result.get("expires_in", 3600)) * 1000)
+    updated = dict(creds)
+    updated["claudeAiOauth"] = oauth
+
+    try:
+        tmp = CREDENTIALS_FILE.parent / (CREDENTIALS_FILE.name + ".tmp")
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+        with os.fdopen(fd, "w") as f:
+            f.write(json.dumps(updated))
+        os.replace(tmp, CREDENTIALS_FILE)
+    except OSError as e:
+        print(f"Warning: refreshed token but could not write {CREDENTIALS_FILE}: {e}", file=sys.stderr)
+
+    return updated
+
+
 def fetch_usage() -> dict:
     """Fetch usage from Anthropic's /api/oauth/usage endpoint.
 
-    Requires a valid (non-expired) OAuth token from ~/.claude/.credentials.json.
+    Reads the OAuth token from ~/.claude/.credentials.json, auto-refreshing it
+    (and persisting the rotated credentials) when expired or rejected.
     The key header is `anthropic-beta: oauth-2025-04-20` — without it, the
     endpoint returns an auth error.
 
@@ -115,42 +168,121 @@ def fetch_usage() -> dict:
     if not token:
         raise RuntimeError("No OAuth access token in credentials")
 
-    expires_at = oauth.get("expiresAt", 0)
-    if time.time() * 1000 > expires_at:
-        raise RuntimeError("OAuth token expired — open Claude Code to refresh it")
+    # Refresh proactively if expired (or about to), then retry once on 401/403
+    # in case the token was revoked early.
+    if time.time() * 1000 > oauth.get("expiresAt", 0) - 60_000:
+        creds = refresh_credentials(creds)
+        token = creds["claudeAiOauth"]["accessToken"]
+
+    for attempt in range(2):
+        req = urllib.request.Request(
+            "https://api.anthropic.com/api/oauth/usage",
+            headers={
+                "Authorization": f"Bearer {token}",
+                "Content-Type": "application/json",
+                "User-Agent": "claude-code/2.1.71",
+                "anthropic-beta": "oauth-2025-04-20",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=10) as resp:
+                return json.loads(resp.read())
+        except urllib.error.HTTPError as e:
+            if e.code in (401, 403) and attempt == 0:
+                creds = refresh_credentials(creds)
+                token = creds["claudeAiOauth"]["accessToken"]
+            else:
+                raise
+
+    raise RuntimeError("Failed to fetch usage after token refresh")
+
+
+# Top-level keys in the cached usage dict that are NOT rate-limit buckets.
+_META_KEYS = {"plan", "source", "updated_at", "extra_usage"}
+
+
+def _bucket_display(short_key: str) -> tuple[str, str]:
+    """Return (full label, statusline abbrev) for a short bucket key.
+
+    Derived from the key so unknown/newly-added buckets get a reasonable
+    label automatically, e.g. "7d_fable" -> ("Week (Fable)", "fab").
+    """
+    known = {
+        "5h": ("Session (5h)", "5h"),
+        "7d": ("Week (all)", "7d"),
+        "7d_opus": ("Week (Opus)", "opus"),
+        "7d_sonnet": ("Week (Sonnet)", "son"),
+    }
+    if short_key in known:
+        return known[short_key]
+    if short_key.startswith("7d_"):
+        model = short_key[3:]
+        return f"Week ({model.replace('_', ' ').title()})", model[:3]
+    return short_key.replace("_", " ").title(), short_key[:4]
+
+
+def _quota_buckets(data: dict):
+    """Yield (short_key, bucket) for each rate-limit bucket in a usage dict.
+
+    Relies on insertion order (build_usage_json inserts them sorted), so
+    callers get a stable, sensible display sequence.
+    """
+    for key, val in data.items():
+        if key in _META_KEYS:
+            continue
+        if isinstance(val, dict) and "pct" in val:
+            yield key, val
 
-    req = urllib.request.Request(
-        "https://api.anthropic.com/api/oauth/usage",
-        headers={
-            "Authorization": f"Bearer {token}",
-            "Content-Type": "application/json",
-            "User-Agent": "claude-code/2.1.71",
-            "anthropic-beta": "oauth-2025-04-20",
-        },
-    )
-    with urllib.request.urlopen(req, timeout=10) as resp:
-        return json.loads(resp.read())
+
+def _buckets_from_limits(limits) -> list:
+    """Parse the API's structured `limits` array into (order, short_key, bucket).
+
+    This is the current API shape. Each entry is self-describing:
+        {"kind": "session"|"weekly_all"|"weekly_scoped", "percent": 58,
+         "resets_at": "...", "scope": {"model": {"display_name": "Fable"}}}
+    Model-scoped weekly limits (Opus, Sonnet, Fable, ...) are keyed by their
+    model name, so a newly added one appears automatically.
+    """
+    out = []
+    for entry in limits:
+        if not isinstance(entry, dict):
+            continue
+        pct = entry.get("percent")
+        if pct is None:
+            continue
+        kind = entry.get("kind")
+        if kind == "session":
+            short_key, order = "5h", 0
+        elif kind == "weekly_all":
+            short_key, order = "7d", 1
+        elif kind == "weekly_scoped":
+            model = (entry.get("scope") or {}).get("model") or {}
+            name = (model.get("display_name") or model.get("id") or "scoped").strip()
+            short_key = "7d_" + name.lower().replace(" ", "_")
+            order = {"7d_opus": 2, "7d_sonnet": 3}.get(short_key, 4)
+        else:
+            short_key, order = kind or "unknown", 5
+        out.append((order, short_key, {"pct": pct, "resets_at": entry.get("resets_at")}))
+    return out
 
 
 def build_usage_json(api_data: dict, plan: str) -> dict:
-    """Transform API response into our cached format."""
+    """Transform API response into our cached format.
+
+    Reads the API's structured `limits` array — every quota it reports (session,
+    weekly-all, and per-model weekly windows like Opus/Sonnet/Fable) is included
+    and mapped to a short key, so a newly added one appears automatically
+    instead of being dropped.
+    """
     result = {
         "plan": plan,
         "source": "api",
         "updated_at": datetime.now(timezone.utc).isoformat(),
     }
-    for key, api_key in [
-        ("5h", "five_hour"),
-        ("7d", "seven_day"),
-        ("7d_sonnet", "seven_day_sonnet"),
-        ("7d_opus", "seven_day_opus"),
-    ]:
-        bucket = api_data.get(api_key)
-        if bucket:
-            result[key] = {
-                "pct": bucket["utilization"],
-                "resets_at": bucket.get("resets_at"),
-            }
+    limits = api_data.get("limits")
+    buckets = _buckets_from_limits(limits) if isinstance(limits, list) else []
+    for _, short_key, bucket in sorted(buckets, key=lambda b: b[0]):
+        result[short_key] = bucket
     extra = api_data.get("extra_usage")
     if extra:
         result["extra_usage"] = extra
@@ -162,13 +294,51 @@ def write_usage_file(data: dict):
     USAGE_FILE.write_text(json.dumps(data, indent=2) + "\n")
 
 
+def _read_cache() -> dict | None:
+    """Read the cached usage file, or None if missing/unreadable."""
+    try:
+        return json.loads(USAGE_FILE.read_text())
+    except Exception:
+        return None
+
+
+def _is_429(err: Exception) -> bool:
+    """True if the exception is (or wraps) an HTTP 429 rate-limit error."""
+    if isinstance(err, urllib.error.HTTPError) and err.code == 429:
+        return True
+    return "429" in str(err)
+
+
+def _cache_age_str(data: dict) -> str:
+    """Return e.g. ' 3m ago' from a usage dict's updated_at, or '' if unknown."""
+    try:
+        updated = datetime.fromisoformat(data["updated_at"])
+        secs = int((datetime.now(timezone.utc) - updated).total_seconds())
+        m = secs // 60
+        return f" {m // 60}h{m % 60}m ago" if m >= 60 else f" {m}m ago"
+    except Exception:
+        return ""
+
+
 # -- CLI commands --
 
 def cmd_status(raw_json=False):
-    """Fetch and display current usage."""
-    api_data = fetch_usage()
-    plan = get_plan()
-    data = build_usage_json(api_data, plan)
+    """Fetch and display current usage.
+
+    Fetches fresh from the API, but on failure (rate limit, offline, expired
+    token) falls back to the last cached usage rather than crashing.
+    """
+    stale = False
+    try:
+        api_data = fetch_usage()
+        data = build_usage_json(api_data, get_plan())
+    except Exception as e:
+        cached = _read_cache()
+        if cached is None:
+            reason = "rate limited (HTTP 429) — try again shortly" if _is_429(e) else str(e)
+            print(f"Could not fetch usage: {reason}", file=sys.stderr)
+            sys.exit(1)
+        data, stale = cached, True
 
     if raw_json:
         print(json.dumps(data, indent=2))
@@ -201,18 +371,12 @@ def cmd_status(raw_json=False):
         except Exception:
             return ""
 
-    print(f"Plan: {plan}")
-    for label, key in [
-        ("Session (5h)", "5h"),
-        ("Week (all)", "7d"),
-        ("Week (Sonnet)", "7d_sonnet"),
-        ("Week (Opus)", "7d_opus"),
-    ]:
-        bucket = data.get(key)
-        if bucket:
-            pct = bucket["pct"]
-            reset = fmt_reset(bucket.get("resets_at"))
-            print(f"  {label:20s} {color_pct(pct)}{D}{reset}{RST}")
+    print(f"Plan: {data.get('plan', '?')}")
+    for key, bucket in _quota_buckets(data):
+        label = _bucket_display(key)[0]
+        pct = bucket["pct"]
+        reset = fmt_reset(bucket.get("resets_at"))
+        print(f"  {label:20s} {color_pct(pct)}{D}{reset}{RST}")
 
     extra = data.get("extra_usage")
     if extra and extra.get("is_enabled"):
@@ -220,6 +384,30 @@ def cmd_status(raw_json=False):
         limit = extra.get("monthly_limit", 0) / 100
         print(f"  {'Extra usage':20s} ${used:.2f} / ${limit:.2f}")
 
+    if stale:
+        age = _cache_age_str(data)
+        print(f"{D}  (cached{age} — live fetch failed){RST}", file=sys.stderr)
+
+
+def cmd_refresh():
+    """Fetch fresh usage from the API and write the cache file once, then exit.
+
+    A one-shot equivalent of a single daemon tick — use it to force
+    ~/.claude/usage-limits.json up to date without running the daemon.
+    """
+    try:
+        api_data = fetch_usage()
+    except Exception as e:
+        reason = "rate limited (HTTP 429) — try again shortly" if _is_429(e) else str(e)
+        print(f"Could not refresh usage: {reason}", file=sys.stderr)
+        sys.exit(1)
+    data = build_usage_json(api_data, get_plan())
+    write_usage_file(data)
+    pcts = " ".join(f"{key}:{int(b['pct'])}%" for key, b in _quota_buckets(data))
+    print(f"Updated {USAGE_FILE}")
+    if pcts:
+        print(f"  {pcts}")
+
 
 def cmd_daemon(interval: int = DAEMON_INTERVAL):
     """Run in foreground, refresh every `interval` seconds."""
@@ -238,11 +426,7 @@ def cmd_daemon(interval: int = DAEMON_INTERVAL):
             data = build_usage_json(api_data, plan)
             write_usage_file(data)
             backoff = 0
-            pcts = []
-            for key in ("5h", "7d", "7d_sonnet"):
-                b = data.get(key)
-                if b:
-                    pcts.append(f"{key}:{int(b['pct'])}%")
+            pcts = [f"{key}:{int(b['pct'])}%" for key, b in _quota_buckets(data)]
             print(f"[{datetime.now().strftime('%H:%M:%S')}] {' '.join(pcts)}")
         except urllib.error.HTTPError as e:
             if e.code == 429:
@@ -328,17 +512,13 @@ def cmd_statusline():
 
     plan = usage.get("plan", "?")
     five_h = usage.get("5h", {})
-    seven_d = usage.get("7d", {})
-    sonnet = usage.get("7d_sonnet", {})
 
     parts = [f"{D}{pwd}{RST}", f"[{C}{model}{RST}]"]
 
-    if five_h:
-        parts.append(f"5h:{color_pct(int(five_h.get('pct', 0)))}")
-    if seven_d:
-        parts.append(f"7d:{color_pct(int(seven_d.get('pct', 0)))}")
-    if sonnet:
-        parts.append(f"son:{color_pct(int(sonnet.get('pct', 0)))}")
+    # Auto-include every quota bucket present (a newly added one just appears).
+    for key, bucket in _quota_buckets(usage):
+        abbrev = _bucket_display(key)[1]
+        parts.append(f"{abbrev}:{color_pct(int(bucket.get('pct', 0)))}")
 
     parts.append(f"| {cost_fmt} | {D}{plan}{RST}")
 
@@ -375,6 +555,7 @@ def main():
     sub = parser.add_subparsers(dest="command")
     sub.add_parser("status", help="Show current usage (default)")
     sub.add_parser("json", help="Print raw JSON")
+    sub.add_parser("refresh", help="Fetch fresh usage and update the cache file once")
     daemon_parser = sub.add_parser("daemon", help="Run refresh daemon")
     daemon_parser.add_argument("-i", "--interval", type=int, default=DAEMON_INTERVAL,
                                help=f"Refresh interval in seconds (default: {DAEMON_INTERVAL})")
@@ -387,6 +568,8 @@ def main():
         cmd_status()
     elif cmd == "json":
         cmd_status(raw_json=True)
+    elif cmd == "refresh":
+        cmd_refresh()
     elif cmd == "daemon":
         cmd_daemon(interval=args.interval)
     elif cmd == "statusline":

ccusage-0.1.8/tests/test_ccusage.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import io
+import json
+import tempfile
+import time
+import unittest
+import urllib.error
+from pathlib import Path
+from unittest import mock
+
+import ccusage
+
+USAGE_URL = "https://api.anthropic.com/api/oauth/usage"
+
+
+def _creds(expires_at: int) -> dict:
+    return {
+        "claudeAiOauth": {
+            "accessToken": "old-token",
+            "refreshToken": "old-refresh",
+            "expiresAt": expires_at,
+            "scopes": ["user:inference"],
+            "subscriptionType": "max",
+        },
+        "otherTopLevel": "keep-me",
+    }
+
+
+class _FakeResponse(io.BytesIO):
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        pass
+
+
+def _json_response(payload: dict) -> _FakeResponse:
+    return _FakeResponse(json.dumps(payload).encode())
+
+
+REFRESH_RESULT = {
+    "access_token": "new-token",
+    "refresh_token": "new-refresh",
+    "expires_in": 28800,
+}
+
+
+class FetchUsageTests(unittest.TestCase):
+    def setUp(self):
+        self._tmp = tempfile.TemporaryDirectory()
+        self.addCleanup(self._tmp.cleanup)
+        self.credfile = Path(self._tmp.name) / ".credentials.json"
+        patcher = mock.patch.object(ccusage, "CREDENTIALS_FILE", self.credfile)
+        patcher.start()
+        self.addCleanup(patcher.stop)
+
+    def _write_creds(self, expires_at: int):
+        self.credfile.write_text(json.dumps(_creds(expires_at)))
+
+    def test_valid_token_skips_refresh(self):
+        self._write_creds(int(time.time() * 1000) + 3_600_000)
+        calls = []
+
+        def fake_urlopen(req, timeout=None):
+            calls.append(req.full_url)
+            self.assertEqual(req.headers["Authorization"], "Bearer old-token")
+            return _json_response({"five_hour": {"utilization": 4.0}})
+
+        with mock.patch.object(ccusage.urllib.request, "urlopen", fake_urlopen):
+            data = ccusage.fetch_usage()
+
+        self.assertEqual(data, {"five_hour": {"utilization": 4.0}})
+        self.assertEqual(calls, [USAGE_URL])
+
+    def test_expired_token_refreshes_and_persists_rotated_credentials(self):
+        self._write_creds(0)
+        calls = []
+
+        def fake_urlopen(req, timeout=None):
+            calls.append(req.full_url)
+            if req.full_url == ccusage.TOKEN_URL:
+                self.assertEqual(
+                    json.loads(req.data),
+                    {
+                        "grant_type": "refresh_token",
+                        "refresh_token": "old-refresh",
+                        "client_id": ccusage.CLIENT_ID,
+                    },
+                )
+                return _json_response(REFRESH_RESULT)
+            self.assertEqual(req.headers["Authorization"], "Bearer new-token")
+            return _json_response({"five_hour": {"utilization": 4.0}})
+
+        with mock.patch.object(ccusage.urllib.request, "urlopen", fake_urlopen):
+            ccusage.fetch_usage()
+
+        self.assertEqual(calls, [ccusage.TOKEN_URL, USAGE_URL])
+
+        on_disk = json.loads(self.credfile.read_text())
+        oauth = on_disk["claudeAiOauth"]
+        self.assertEqual(oauth["accessToken"], "new-token")
+        self.assertEqual(oauth["refreshToken"], "new-refresh")
+        self.assertGreater(oauth["expiresAt"], time.time() * 1000)
+        # Fields not returned by the token endpoint must survive the rewrite
+        self.assertEqual(oauth["scopes"], ["user:inference"])
+        self.assertEqual(oauth["subscriptionType"], "max")
+        self.assertEqual(on_disk["otherTopLevel"], "keep-me")
+        self.assertEqual(self.credfile.stat().st_mode & 0o777, 0o600)
+
+    def test_rejected_token_retries_once_after_refresh(self):
+        self._write_creds(int(time.time() * 1000) + 3_600_000)
+        state = {"rejected": False}
+
+        def fake_urlopen(req, timeout=None):
+            if req.full_url == ccusage.TOKEN_URL:
+                return _json_response(REFRESH_RESULT)
+            if not state["rejected"]:
+                state["rejected"] = True
+                raise urllib.error.HTTPError(req.full_url, 401, "Unauthorized", {}, io.BytesIO(b""))
+            self.assertEqual(req.headers["Authorization"], "Bearer new-token")
+            return _json_response({"ok": True})
+
+        with mock.patch.object(ccusage.urllib.request, "urlopen", fake_urlopen):
+            self.assertEqual(ccusage.fetch_usage(), {"ok": True})
+
+        on_disk = json.loads(self.credfile.read_text())
+        self.assertEqual(on_disk["claudeAiOauth"]["accessToken"], "new-token")
+
+    def test_persistent_rejection_raises(self):
+        self._write_creds(int(time.time() * 1000) + 3_600_000)
+
+        def fake_urlopen(req, timeout=None):
+            if req.full_url == ccusage.TOKEN_URL:
+                return _json_response(REFRESH_RESULT)
+            raise urllib.error.HTTPError(req.full_url, 401, "Unauthorized", {}, io.BytesIO(b""))
+
+        with mock.patch.object(ccusage.urllib.request, "urlopen", fake_urlopen):
+            with self.assertRaises(urllib.error.HTTPError):
+                ccusage.fetch_usage()
+
+    def test_expired_token_without_refresh_token_raises(self):
+        creds = _creds(0)
+        del creds["claudeAiOauth"]["refreshToken"]
+        self.credfile.write_text(json.dumps(creds))
+
+        with self.assertRaisesRegex(RuntimeError, "no refresh token"):
+            ccusage.fetch_usage()
+
+    def test_refresh_endpoint_error_raises_runtime_error(self):
+        self._write_creds(0)
+
+        def fake_urlopen(req, timeout=None):
+            raise urllib.error.HTTPError(req.full_url, 429, "Too Many Requests", {}, io.BytesIO(b""))
+
+        with mock.patch.object(ccusage.urllib.request, "urlopen", fake_urlopen):
+            with self.assertRaisesRegex(RuntimeError, "Token refresh failed \\(429\\)"):
+                ccusage.fetch_usage()
+
+
+class BuildUsageJsonTests(unittest.TestCase):
+    def test_reads_structured_limits_array(self):
+        # Current API shape: session/weekly totals and the model-scoped Fable
+        # quota all live in `limits`; the flat seven_day_* keys are ignored.
+        api_data = {
+            "seven_day_opus": None,
+            "seven_day_sonnet": None,
+            "iguana_necktie": None,
+            "limits": [
+                {"kind": "session", "percent": 3, "resets_at": "2026-07-04T05:10:00+00:00"},
+                {"kind": "weekly_all", "percent": 33, "resets_at": "2026-07-07T13:00:00+00:00"},
+                {"kind": "weekly_scoped", "percent": 58,
+                 "resets_at": "2026-07-07T13:00:00+00:00",
+                 "scope": {"model": {"id": None, "display_name": "Fable"}}},
+            ],
+            "extra_usage": {"is_enabled": True, "monthly_limit": 100000},
+        }
+        result = ccusage.build_usage_json(api_data, "max_20x")
+        self.assertEqual(result["plan"], "max_20x")
+        self.assertEqual(result["5h"], {"pct": 3, "resets_at": "2026-07-04T05:10:00+00:00"})
+        self.assertEqual(result["7d"], {"pct": 33, "resets_at": "2026-07-07T13:00:00+00:00"})
+        self.assertEqual(result["7d_fable"], {"pct": 58, "resets_at": "2026-07-07T13:00:00+00:00"})
+        self.assertEqual(result["extra_usage"], {"is_enabled": True, "monthly_limit": 100000})
+        self.assertEqual(ccusage._bucket_display("7d_fable"), ("Week (Fable)", "fab"))
+        # Buckets appear in a stable, sensible order.
+        keys = [k for k, _ in ccusage._quota_buckets(result)]
+        self.assertEqual(keys, ["5h", "7d", "7d_fable"])
+
+    def test_scoped_limit_without_percent_is_skipped(self):
+        api_data = {"limits": [
+            {"kind": "weekly_scoped", "percent": None,
+             "scope": {"model": {"display_name": "Opus"}}},
+        ]}
+        result = ccusage.build_usage_json(api_data, "max_20x")
+        self.assertEqual([k for k, _ in ccusage._quota_buckets(result)], [])
+
+
+if __name__ == "__main__":
+    unittest.main()

{ccusage-0.1.6 → ccusage-0.1.8}/uv.lock

@@ -4,5 +4,5 @@ requires-python = ">=3.12"
 
 [[package]]
 name = "ccusage"
-version = "0.1.4"
+version = "0.1.8"
 source = { editable = "." }