tokenmaxxr 1.0.0__py3-none-any.whl

tokenmaxxr/__init__.py

@@ -0,0 +1,20 @@
+"""tokenmaxxr — aggregate AI subscription quota usage into one view."""
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+try:
+    __version__ = _pkg_version("tokenmaxxr")
+except PackageNotFoundError:  # running from raw checkout, not installed
+    __version__ = "0.0.0+unknown"
+
+from tokenmaxxr.schema import ProviderResult, UsageWindow, build_document, status_of
+from tokenmaxxr.fetch import fetch_all
+
+__all__ = [
+    "ProviderResult",
+    "UsageWindow",
+    "build_document",
+    "fetch_all",
+    "status_of",
+    "__version__",
+]

tokenmaxxr/_webui/dist/app.js

@@ -0,0 +1,160 @@
+// tokenmaxxr WebUI — vanilla JS, no build step.
+const $ = (sel) => document.querySelector(sel);
+const cards = $("#cards");
+const providerSel = $("#provider");
+const windowSel = $("#window");
+const chart = $("#chart");
+const historySec = $("#history");
+const auto = $("#auto");
+let timer = null;
+
+async function jget(url) {
+  const r = await fetch(url);
+  if (!r.ok) throw new Error(`${url}: ${r.status}`);
+  return r.json();
+}
+async function jpost(url) {
+  const r = await fetch(url, { method: "POST" });
+  if (!r.ok) throw new Error(`${url}: ${r.status}`);
+  return r.json();
+}
+
+function fmtPct(n) {
+  return `${Math.max(0, Math.min(100, n || 0))}%`;
+}
+function fmtReset(iso) {
+  if (!iso) return "";
+  try {
+    const d = new Date(iso);
+    const diff = d - Date.now();
+    if (diff < 0) return "now";
+    const m = Math.floor(diff / 60000);
+    if (m < 60) return `${m}m`;
+    const h = Math.floor(m / 60);
+    if (h < 24) return `${h}h`;
+    return `${Math.floor(h / 24)}d`;
+  } catch { return ""; }
+}
+
+function renderCard(p) {
+  const div = document.createElement("div");
+  div.className = "card";
+  const head = document.createElement("h2");
+  head.textContent = p.name;
+  const status = document.createElement("span");
+  status.className = `status ${p.status}`;
+  status.textContent = p.status;
+  head.appendChild(status);
+  div.appendChild(head);
+  if (p.error) {
+    const e = document.createElement("div");
+    e.className = "status error";
+    e.textContent = p.error;
+    div.appendChild(e);
+  }
+  for (const w of p.windows || []) {
+    const row = document.createElement("div");
+    row.className = "window";
+    const label = document.createElement("div");
+    label.className = "row";
+    const pct = w.pct_used || 0;
+    label.innerHTML = `<span>${w.label}</span><span>${fmtPct(pct)} · ${fmtReset(w.reset_at)}</span>`;
+    const bar = document.createElement("div");
+    const cls = pct >= 90 ? "err" : pct >= 70 ? "warn" : "";
+    bar.className = `bar ${cls}`;
+    bar.innerHTML = `<span style="width:${pct}%"></span>`;
+    row.appendChild(label);
+    row.appendChild(bar);
+    div.appendChild(row);
+  }
+  return div;
+}
+
+async function loadUsage() {
+  const doc = await jget("/api/usage");
+  cards.innerHTML = "";
+  for (const p of doc.providers) cards.appendChild(renderCard(p));
+  // Populate provider filter
+  const existing = new Set([...providerSel.options].map(o => o.value));
+  for (const p of doc.providers) {
+    if (!existing.has(p.id)) {
+      const opt = document.createElement("option");
+      opt.value = p.id;
+      opt.textContent = p.name;
+      providerSel.appendChild(opt);
+    }
+  }
+  historySec.hidden = false;
+  await loadHistory();
+}
+
+async function loadHistory() {
+  const params = new URLSearchParams();
+  if (providerSel.value) params.set("provider", providerSel.value);
+  if (windowSel.value) params.set("window", windowSel.value);
+  const rows = await jget(`/api/history?${params}`);
+  drawChart(rows);
+}
+
+function drawChart(rows) {
+  const ctx = chart.getContext("2d");
+  ctx.clearRect(0, 0, chart.width, chart.height);
+  if (!rows.length) {
+    ctx.fillStyle = "#888";
+    ctx.fillText("no history yet", 12, 24);
+    return;
+  }
+  // Group by window
+  const byWin = new Map();
+  for (const r of rows) {
+    if (!byWin.has(r.window)) byWin.set(r.window, []);
+    byWin.get(r.window).push(r);
+  }
+  const padX = 40, padY = 10;
+  const w = chart.width - padX * 2;
+  const h = chart.height - padY * 2;
+  ctx.strokeStyle = "#888";
+  ctx.beginPath();
+  ctx.moveTo(padX, padY + h);
+  ctx.lineTo(padX + w, padY + h);
+  ctx.stroke();
+  const colors = { "5h": "#059669", "7d": "#2563eb", "30d": "#d97706" };
+  for (const [win, pts] of byWin) {
+    pts.sort((a, b) => a.ts.localeCompare(b.ts));
+    ctx.strokeStyle = colors[win] || "#888";
+    ctx.beginPath();
+    pts.forEach((p, i) => {
+      const x = padX + (i / Math.max(1, pts.length - 1)) * w;
+      const y = padY + h - (p.pct_used / 100) * h;
+      i ? ctx.lineTo(x, y) : ctx.moveTo(x, y);
+    });
+    ctx.stroke();
+    // legend
+    ctx.fillStyle = colors[win] || "#888";
+    ctx.fillText(win, padX + ([...byWin.keys()].indexOf(win)) * 30, padY + 12);
+  }
+}
+
+$("#refresh").addEventListener("click", async () => {
+  $("#refresh").textContent = "refreshing…";
+  try {
+    await jpost("/api/refresh");
+    await loadUsage();
+  } finally {
+    $("#refresh").textContent = "refresh now";
+  }
+});
+providerSel.addEventListener("change", loadHistory);
+windowSel.addEventListener("change", loadHistory);
+auto.addEventListener("change", () => {
+  if (auto.checked) {
+    timer = setInterval(loadUsage, 60_000);
+  } else if (timer) {
+    clearInterval(timer);
+    timer = null;
+  }
+});
+
+loadUsage().catch((e) => {
+  cards.textContent = `Error: ${e.message}`;
+});

tokenmaxxr/_webui/dist/index.html

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>tokenmaxxr</title>
+    <link rel="stylesheet" href="./styles.css" />
+  </head>
+  <body>
+    <header>
+      <h1>tokenmaxxr</h1>
+      <div class="controls">
+        <label><input type="checkbox" id="auto" /> auto-refresh</label>
+        <button id="refresh">refresh now</button>
+      </div>
+    </header>
+    <main id="cards"></main>
+    <section id="history" hidden>
+      <h2>history</h2>
+      <select id="provider">
+        <option value="">all providers</option>
+      </select>
+      <select id="window">
+        <option value="">all windows</option>
+        <option>5h</option>
+        <option>7d</option>
+        <option>30d</option>
+      </select>
+      <canvas id="chart" width="600" height="160"></canvas>
+    </section>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

tokenmaxxr/_webui/dist/styles.css

@@ -0,0 +1,36 @@
+:root {
+  color-scheme: light dark;
+  --bg: #fff;
+  --fg: #111;
+  --muted: #888;
+  --card: #f5f5f7;
+  --warn: #d97706;
+  --err: #dc2626;
+  --ok: #059669;
+}
+@media (prefers-color-scheme: dark) {
+  :root { --bg:#0b0b0c; --fg:#eee; --muted:#888; --card:#1a1a1d; }
+}
+* { box-sizing: border-box; }
+body { margin: 0; font: 14px/1.4 system-ui, sans-serif; background: var(--bg); color: var(--fg); }
+header { display: flex; justify-content: space-between; align-items: center; padding: 12px 20px; border-bottom: 1px solid var(--muted); }
+h1 { font-size: 18px; margin: 0; }
+.controls { display: flex; gap: 12px; align-items: center; }
+button { background: var(--card); color: var(--fg); border: 1px solid var(--muted); border-radius: 6px; padding: 4px 10px; cursor: pointer; }
+main { display: grid; gap: 12px; grid-template-columns: repeat(auto-fill, minmax(260px, 1fr)); padding: 20px; }
+.card { background: var(--card); border-radius: 8px; padding: 14px; }
+.card h2 { font-size: 14px; margin: 0 0 6px; display: flex; justify-content: space-between; }
+.card .status { font-size: 12px; color: var(--muted); }
+.card .status.error { color: var(--err); }
+.card .status.no-auth { color: var(--warn); }
+.card .status.stale { color: var(--warn); }
+.window { margin: 8px 0; }
+.window .row { display: flex; justify-content: space-between; font-size: 12px; color: var(--muted); }
+.bar { background: var(--bg); border-radius: 4px; height: 6px; overflow: hidden; margin: 4px 0; }
+.bar > span { display: block; height: 100%; background: var(--ok); }
+.bar.warn > span { background: var(--warn); }
+.bar.err > span { background: var(--err); }
+#history { padding: 0 20px 24px; }
+#history h2 { font-size: 14px; }
+#history select { margin-right: 8px; }
+canvas { background: var(--card); border-radius: 8px; padding: 8px; max-width: 100%; }

tokenmaxxr/cache.py

@@ -0,0 +1,125 @@
+"""Per-provider TTL cache.
+
+Backed by JSON files under $XDG_STATE_HOME/tokenmaxxr/cache/<slug>.json
+(defaults to ~/.local/state/tokenmaxxr/cache). Each entry stores
+{fetched_at: iso, payload: {...normalized provider result...}}.
+
+`--refresh` is a cache invalidation flag handled by the caller
+(tokenmaxxr.fetch), not by this module.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from tokenmaxxr.schema import ProviderResult, UsageWindow
+
+DEFAULT_TTL_SECONDS = 300
+
+
+def state_dir() -> Path:
+    base = os.environ.get("XDG_STATE_HOME") or os.path.expanduser(
+        "~/.local/state"
+    )
+    return Path(base) / "tokenmaxxr"
+
+
+def cache_dir() -> Path:
+    d = state_dir() / "cache"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def history_path() -> Path:
+    d = state_dir()
+    d.mkdir(parents=True, exist_ok=True)
+    return d / "history.jsonl"
+
+
+def _path_for(slug: str) -> Path:
+    safe = slug.replace("/", "_")
+    return cache_dir() / f"{safe}.json"
+
+
+def read(slug: str, *, ttl: int = DEFAULT_TTL_SECONDS) -> ProviderResult | None:
+    """Return a fresh cached result, or None on miss / stale."""
+    path = _path_for(slug)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    fetched_at = data.get("fetched_at")
+    payload = data.get("payload")
+    if not isinstance(fetched_at, str) or not isinstance(payload, dict):
+        return None
+    try:
+        ts = datetime.fromisoformat(fetched_at.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    age = (datetime.now(timezone.utc) - ts).total_seconds()
+    if age > ttl:
+        return None
+    return _payload_to_result(slug, payload, status="ok")
+
+
+def read_any_age(slug: str) -> ProviderResult | None:
+    """Return the cached result regardless of age (for stale fallback)."""
+    path = _path_for(slug)
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+    except (OSError, json.JSONDecodeError):
+        return None
+    payload = data.get("payload")
+    if not isinstance(payload, dict):
+        return None
+    return _payload_to_result(slug, payload, status="stale")
+
+
+def write(slug: str, result: ProviderResult) -> None:
+    path = _path_for(slug)
+    payload = {
+        "id": result.id,
+        "name": result.name,
+        "windows": [asdict(w) for w in result.windows],
+    }
+    data = {
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+        "payload": payload,
+    }
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data))
+    tmp.replace(path)
+
+
+def invalidate(slug: str) -> None:
+    path = _path_for(slug)
+    if path.exists():
+        path.unlink()
+
+
+def _payload_to_result(
+    slug: str, payload: dict, *, status: str
+) -> ProviderResult:
+    return ProviderResult(
+        id=payload.get("id", slug),
+        name=payload.get("name", slug),
+        status=status,  # type: ignore[arg-type]
+        windows=[
+            UsageWindow(
+                label=w["label"],
+                pct_used=int(w["pct_used"]),
+                reset_at=w.get("reset_at"),
+            )
+            for w in payload.get("windows", [])
+            if isinstance(w, dict) and "label" in w and "pct_used" in w
+        ],
+    )

tokenmaxxr/cli.py

@@ -0,0 +1,163 @@
+"""`tokenmaxxr` CLI entry point."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Sequence
+
+from tokenmaxxr import __version__
+from tokenmaxxr import cookies as _cookies
+from tokenmaxxr import fetch_all
+from tokenmaxxr.cookies import discover_sources
+from tokenmaxxr.providers import get_provider, known_slugs
+from tokenmaxxr.schema import dumps
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "doctor":
+        return _cmd_doctor(args)
+    if args.command == "serve":
+        return _cmd_serve(args)
+
+    overrides = _parse_cookie_overrides(getattr(args, "cookie_file", []) or [])
+    try:
+        doc = fetch_all(
+            providers=getattr(args, "provider", None),
+            cookie_overrides=overrides or None,
+            refresh=getattr(args, "refresh", False),
+        )
+    except FileNotFoundError as e:
+        sys.stderr.write(f"tokenmaxxr: {e}\n")
+        return 2
+
+    if args.json:
+        sys.stdout.write(dumps(doc) + "\n")
+        return 0
+
+    _print_table(doc)
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="tokenmaxxr",
+        description="Aggregate AI subscription quota usage.",
+    )
+    p.add_argument(
+        "--version", action="version", version=f"tokenmaxxr {__version__}"
+    )
+    p.add_argument(
+        "--json", action="store_true", help="emit one JSON document on stdout"
+    )
+    p.add_argument(
+        "--provider",
+        action="append",
+        default=None,
+        help="limit to provider slug (repeatable)",
+    )
+    p.add_argument(
+        "--refresh",
+        action="store_true",
+        help="ignore the cache and re-fetch live",
+    )
+    p.add_argument(
+        "--cookie-file",
+        action="append",
+        default=[],
+        metavar="SLUG=PATH",
+        help="override cookie store path (repeatable)",
+    )
+    sub = p.add_subparsers(dest="command", required=False)
+
+    sub.add_parser("doctor", help="show which cookie stores could be used per provider")
+
+    serve = sub.add_parser("serve", help="run the local web dashboard")
+    serve.add_argument("--host", default="127.0.0.1")
+    serve.add_argument("--port", type=int, default=8765)
+
+    return p
+
+
+def _parse_cookie_overrides(items: list[str]) -> dict[str, str]:
+    out: dict[str, str] = {}
+    for item in items:
+        if "=" not in item:
+            raise SystemExit(f"--cookie-file expects SLUG=PATH, got: {item!r}")
+        k, v = item.split("=", 1)
+        out[k.strip()] = v.strip()
+    return out
+
+
+def _print_table(doc: dict) -> None:
+    rows: list[tuple[str, str, str, str, str]] = []
+    for prov in doc.get("providers", []):
+        name = prov.get("name") or prov.get("id") or "?"
+        status = prov.get("status", "?")
+        windows = prov.get("windows") or []
+        if windows:
+            label = ", ".join(
+                f"{w.get('label','?')}:{w.get('pct_used',0)}%" for w in windows
+            )
+        else:
+            label = "(no windows)"
+        reset = ""
+        if windows:
+            # Pick the first window that actually has a reset time. The
+            # "primary" window may legitimately be None (e.g. 5h on
+            # ClinePass has no resetsAt), so fall through to the next
+            # window instead of always taking the first.
+            for w in windows:
+                ts = w.get("reset_at")
+                if ts:
+                    reset = ts
+                    break
+        rows.append((name, status, label, reset, prov.get("error") or ""))
+    widths = [max(len(str(r[i])) for r in rows + [("",)*5]) for i in range(5)]
+    fmt = "  ".join(f"{{:<{w}}}" for w in widths)
+    print(fmt.format("PROVIDER", "STATUS", "USAGE", "RESET", "ERROR"))
+    for r in rows:
+        print(fmt.format(*r))
+
+
+def _cmd_doctor(args: argparse.Namespace) -> int:
+    # Use the module reference so monkeypatching `cookies.discover_sources` is
+    # picked up here (it would be missed if we imported the name directly).
+    lines: list[str] = []
+    for slug in known_slugs():
+        prov = get_provider(slug)
+        sources = _cookies.discover_sources(prov.cookie_domain)
+        lines.append(f"# {prov.name} ({slug}) — domain: {prov.cookie_domain}")
+        if not sources:
+            lines.append("  no cookie stores discovered")
+            lines.append(
+                f"  remediation: log in to {prov.cookie_domain} in your browser, "
+                "or pass --cookie-file SLUG=/path/to/cookies.sqlite"
+            )
+        else:
+            for s in sources:
+                lines.append(f"  - {s.kind}: {s.detail}")
+        lines.append("")
+    sys.stdout.write("\n".join(lines))
+    return 0
+
+
+def _cmd_serve(args: argparse.Namespace) -> int:
+    try:
+        from tokenmaxxr.serve import run
+    except ImportError as e:
+        sys.stderr.write(
+            "serve requires the [serve] extra: pip install 'tokenmaxxr[serve]'\n"
+            f"  ({e})"
+        )
+        return 2
+    run(host=getattr(args, "host", "127.0.0.1"), port=getattr(args, "port", 8765))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())