tokenwatch 0.2.0__py3-none-any.whl

tokenwatch/__init__.py

@@ -0,0 +1,2 @@
+"""TokenWatch — Real-time Claude Code cost dashboard."""
+__version__ = "0.2.0"

tokenwatch/alerts.py

@@ -0,0 +1,142 @@
+"""
+alerts.py — Desktop notifications + weekly email digest.
+
+Notifications work on:
+  macOS   — osascript
+  Linux   — notify-send (libnotify)
+  Windows — win10toast or plyer fallback
+
+Email digest uses Resend (free tier: 3000 emails/mo).
+Set RESEND_API_KEY env var + digest_email in config to enable.
+"""
+
+import logging
+import os
+import platform
+import subprocess
+from datetime import date, timedelta
+
+logger = logging.getLogger(__name__)
+
+
+# ── Desktop notifications ─────────────────────────────────────────────────────
+
+def notify(title: str, message: str) -> None:
+    """Send a desktop notification. Silently fails if not supported."""
+    system = platform.system()
+    try:
+        if system == "Darwin":
+            script = f'display notification "{message}" with title "{title}" sound name "Tink"'
+            subprocess.run(["osascript", "-e", script], capture_output=True, timeout=3)
+
+        elif system == "Linux":
+            subprocess.run(
+                ["notify-send", title, message, "--app-name=TokenWatch", "--icon=dialog-information"],
+                capture_output=True, timeout=3,
+            )
+
+        elif system == "Windows":
+            try:
+                from win10toast import ToastNotifier
+                ToastNotifier().show_toast(title, message, duration=5, threaded=True)
+            except ImportError:
+                try:
+                    import plyer
+                    plyer.notification.notify(title=title, message=message, app_name="TokenWatch")
+                except ImportError:
+                    logger.debug("No Windows notification library available (win10toast / plyer).")
+
+    except Exception as e:
+        logger.debug(f"Notification failed: {e}")
+
+
+# ── Budget alert state ────────────────────────────────────────────────────────
+
+_alert_sent: set[str] = set()
+
+
+def check_budget(cost: float, budget: float, thresholds: list[int]) -> None:
+    """Fire a notification when cost crosses a budget threshold."""
+    today = str(date.today())
+    for pct in thresholds:
+        key = f"{today}-{pct}"
+        if cost >= budget * (pct / 100) and key not in _alert_sent:
+            _alert_sent.add(key)
+            msg = f"${cost:.2f} spent today — {pct}% of your ${budget:.0f} budget"
+            notify("TokenWatch Budget Alert", msg)
+            logger.info(f"Budget alert sent: {pct}%")
+
+
+def reset_alerts() -> None:
+    """Call at midnight to allow today's alerts to fire again tomorrow."""
+    _alert_sent.clear()
+
+
+# ── Weekly email digest ───────────────────────────────────────────────────────
+
+def send_weekly_digest(to_email: str, sessions_data: list[dict]) -> bool:
+    """
+    Send a weekly cost summary email via Resend.
+    Requires RESEND_API_KEY environment variable.
+    Returns True on success.
+    """
+    api_key = os.environ.get("RESEND_API_KEY", "")
+    if not api_key or not to_email:
+        logger.debug("Digest skipped: no RESEND_API_KEY or no email configured.")
+        return False
+
+    try:
+        import urllib.request, json as _json
+
+        total = sum(s.get("total_cost", 0) for s in sessions_data)
+        week_ago = str(date.today() - timedelta(days=7))
+        top_projects: dict[str, float] = {}
+        for s in sessions_data:
+            p = s.get("project", "unknown")
+            top_projects[p] = round(top_projects.get(p, 0) + s.get("total_cost", 0), 4)
+
+        top = sorted(top_projects.items(), key=lambda x: x[1], reverse=True)[:5]
+        rows = "".join(
+            f"<tr><td style='padding:6px 12px;border-bottom:1px solid #eee'>{p}</td>"
+            f"<td style='padding:6px 12px;border-bottom:1px solid #eee;text-align:right'>${c:.4f}</td></tr>"
+            for p, c in top
+        )
+
+        html = f"""
+        <div style="font-family:-apple-system,sans-serif;max-width:480px;margin:0 auto;color:#1a1a18">
+          <h2 style="font-size:18px;font-weight:500;margin-bottom:4px">Your Claude Code spend last week</h2>
+          <p style="color:#6b6a64;margin-bottom:24px;font-size:13px">{week_ago} → {date.today()}</p>
+          <div style="background:#f8f7f4;border-radius:12px;padding:20px;margin-bottom:20px;text-align:center">
+            <p style="font-size:36px;font-weight:500;margin:0">${total:.2f}</p>
+            <p style="color:#6b6a64;font-size:13px;margin:4px 0 0">{len(sessions_data)} sessions</p>
+          </div>
+          <p style="font-size:12px;font-weight:500;text-transform:uppercase;letter-spacing:.05em;color:#6b6a64;margin-bottom:8px">By project</p>
+          <table style="width:100%;border-collapse:collapse;font-size:13px">{rows}</table>
+          <p style="margin-top:24px;font-size:12px;color:#6b6a64">
+            TokenWatch · <a href="http://localhost:7842" style="color:#178BCA">Open dashboard</a>
+          </p>
+        </div>
+        """
+
+        payload = _json.dumps({
+            "from":    "TokenWatch <digest@tokenwatch.dev>",
+            "to":      [to_email],
+            "subject": f"Your Claude Code bill last week: ${total:.2f}",
+            "html":    html,
+        }).encode()
+
+        req = urllib.request.Request(
+            "https://api.resend.com/emails",
+            data=payload,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type":  "application/json",
+            },
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            logger.info(f"Digest sent to {to_email} (status {resp.status})")
+            return True
+
+    except Exception as e:
+        logger.warning(f"Digest send failed: {e}")
+        return False

tokenwatch/cli.py

@@ -0,0 +1,170 @@
+"""
+cli.py — `tokenwatch` command.
+
+tokenwatch              start dashboard
+tokenwatch start        start dashboard
+tokenwatch status       print today's cost
+tokenwatch export       export to CSV/JSON
+tokenwatch seed         generate demo data
+tokenwatch seed --clean remove demo data
+tokenwatch config       show config
+tokenwatch license      activate Pro license
+"""
+
+import argparse
+import sys
+import threading
+import webbrowser
+
+
+def cmd_start(args) -> None:
+    from tokenwatch import config as cfg_module
+    import uvicorn
+
+    cfg = cfg_module.load()
+    if args.budget is not None:
+        cfg["daily_budget"] = args.budget
+        cfg_module.save(cfg)
+    if args.port:
+        cfg["port"] = args.port
+        cfg_module.save(cfg)
+
+    port         = cfg["port"]
+    open_browser = cfg["open_browser"] and not args.no_browser
+    url          = f"http://localhost:{port}"
+
+    from tokenwatch import __version__
+    print(f"\n  ● TokenWatch v{__version__}")
+    print(f"  Dashboard → {url}")
+    print(f"  Budget    → ${cfg['daily_budget']:.2f}/day")
+    print(f"  Press Ctrl+C to stop\n")
+
+    if open_browser:
+        threading.Timer(1.4, lambda: webbrowser.open(url)).start()
+
+    uvicorn.run("tokenwatch.main:app", host="127.0.0.1", port=port, log_level="warning")
+
+
+def cmd_status(args) -> None:
+    from tokenwatch.parser import get_daily_summary, get_today_cost
+    from tokenwatch import config as cfg_module
+
+    cfg    = cfg_module.load()
+    budget = cfg.get("daily_budget", 10.0)
+    cost   = get_today_cost()
+    pct    = cost / budget * 100 if budget else 0
+    summary = get_daily_summary(days=7)
+    max_cost = max((d["cost"] for d in summary), default=1) or 1
+
+    print(f"\n  TokenWatch — today")
+    print(f"  Spent   : ${cost:.4f}  ({pct:.1f}% of ${budget:.0f} budget)")
+    if summary:
+        print(f"\n  Last 7 days:")
+        for d in summary[-7:]:
+            bar = "█" * int(d["cost"] / max_cost * 20)
+            print(f"  {d['date']}  {bar:<20} ${d['cost']:.4f}")
+    print()
+
+
+def cmd_export(args) -> None:
+    from tokenwatch.parser import export_csv, get_all_sessions
+    from pathlib import Path
+    import json
+
+    if args.format == "csv":
+        out = export_csv(days=args.days)
+        fname = "tokenwatch-export.csv"
+        Path(fname).write_text(out)
+        print(f"Exported to {fname}")
+    else:
+        data = [s.to_dict() for s in get_all_sessions(days=args.days)]
+        fname = "tokenwatch-export.json"
+        Path(fname).write_text(json.dumps(data, indent=2))
+        print(f"Exported {len(data)} sessions to {fname}")
+
+
+def cmd_seed(args) -> None:
+    from tokenwatch import seed_demo
+    if args.clean:
+        seed_demo.clean()
+    else:
+        seed_demo.generate(days=args.days)
+
+
+def cmd_config(args) -> None:
+    from tokenwatch import config as cfg_module
+    cfg = cfg_module.load()
+    print(f"\n  Config → {cfg_module.CONFIG_FILE}\n")
+    for k, v in cfg.items():
+        if k == "license_key" and v:
+            v = v[:4] + "…" + v[-4:] if len(v) >= 8 else "set"
+        print(f"  {k:<22} {v}")
+    print()
+
+
+def cmd_license(args) -> None:
+    from tokenwatch.license_check import validate
+    from tokenwatch import config as cfg_module
+
+    key = args.key or input("Enter your license key: ").strip()
+    if not key:
+        print("No key entered.")
+        return
+
+    print("Validating…")
+    result = validate(key)
+
+    if result["valid"]:
+        cfg = cfg_module.load()
+        cfg["license_key"] = key
+        cfg_module.save(cfg)
+        print(f"✓ License activated ({result['plan']} plan)")
+    else:
+        print(f"✗ Invalid license: {result.get('message', '')}")
+        print("  Get a license at https://tokenwatch.dev")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="tokenwatch", description="Real-time Claude Code cost dashboard")
+    sub = parser.add_subparsers(dest="command")
+
+    p_start = sub.add_parser("start")
+    p_start.add_argument("--port",       type=int,   default=None)
+    p_start.add_argument("--no-browser", action="store_true")
+    p_start.add_argument("--budget",     type=float, default=None)
+
+    sub.add_parser("status")
+
+    p_exp = sub.add_parser("export")
+    p_exp.add_argument("--format", choices=["csv", "json"], default="csv")
+    p_exp.add_argument("--days",   type=int, default=30)
+
+    p_seed = sub.add_parser("seed")
+    p_seed.add_argument("--days",  type=int, default=30)
+    p_seed.add_argument("--clean", action="store_true")
+
+    sub.add_parser("config")
+
+    p_lic = sub.add_parser("license")
+    p_lic.add_argument("--key", type=str, default=None)
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        args.command    = "start"
+        args.port       = None
+        args.no_browser = False
+        args.budget     = None
+
+    {
+        "start":   cmd_start,
+        "status":  cmd_status,
+        "export":  cmd_export,
+        "seed":    cmd_seed,
+        "config":  cmd_config,
+        "license": cmd_license,
+    }[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

tokenwatch/config.py

@@ -0,0 +1,50 @@
+"""
+config.py — User configuration for TokenWatch.
+
+Settings are stored in ~/.claude/tokenwatch_config.json
+Edit the file directly, or use the /api/config endpoint.
+"""
+
+import json
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+CONFIG_FILE = Path.home() / ".claude" / "tokenwatch_config.json"
+
+DEFAULTS: dict = {
+    "daily_budget":       10.00,   # USD — alert thresholds are % of this
+    "alert_at_pct":       [80, 100],  # fire desktop notification at these %
+    "history_days":       30,      # how many days of sessions to keep in memory
+    "port":               7842,
+    "open_browser":       True,    # open browser automatically on `tokenwatch` start
+    "digest_email":       "",      # leave blank to disable weekly email digest
+}
+
+
+def load() -> dict:
+    try:
+        if CONFIG_FILE.exists():
+            stored = json.loads(CONFIG_FILE.read_text())
+            # Merge with defaults so new keys are always present
+            return {**DEFAULTS, **stored}
+    except Exception as e:
+        logger.warning(f"Could not read config: {e}")
+    return dict(DEFAULTS)
+
+
+def save(cfg: dict) -> None:
+    try:
+        CONFIG_FILE.parent.mkdir(parents=True, exist_ok=True)
+        CONFIG_FILE.write_text(json.dumps(cfg, indent=2))
+        logger.info(f"Config saved to {CONFIG_FILE}")
+    except Exception as e:
+        logger.warning(f"Could not save config: {e}")
+
+
+def update(key: str, value) -> dict:
+    cfg = load()
+    cfg[key] = value
+    save(cfg)
+    return cfg

tokenwatch/license_check.py

@@ -0,0 +1,126 @@
+"""
+license_check.py — License key validation for Pro features.
+
+Free tier: full local dashboard, 30-day history, CSV export.
+Pro tier ($9/mo): weekly email digest, team report endpoint, update priority.
+
+Validation hits a lightweight endpoint on tokenwatch.dev.
+If offline, falls back to local cache (grace period: 7 days).
+"""
+
+import hashlib
+import json
+import logging
+import time
+import urllib.request
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+VALIDATION_URL = "https://api.tokenwatch.observer/api/validate"   # your backend
+CACHE_FILE      = Path.home() / ".claude" / "tokenwatch_license.json"
+GRACE_PERIOD    = 7 * 86400   # 7 days offline grace
+
+_is_pro:        bool  = False
+_license_key:   str   = ""
+_last_validated: float = 0.0
+
+
+def _load_cache() -> dict:
+    try:
+        if CACHE_FILE.exists():
+            return json.loads(CACHE_FILE.read_text())
+    except Exception:
+        pass
+    return {}
+
+
+def _save_cache(key: str, valid: bool) -> None:
+    try:
+        CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        CACHE_FILE.write_text(json.dumps({
+            "key":        key,
+            "valid":      valid,
+            "checked_at": time.time(),
+        }))
+    except Exception:
+        pass
+
+
+def validate(key: str) -> dict:
+    """
+    Validate a license key.
+    Returns {"valid": bool, "plan": str, "message": str}
+    """
+    global _is_pro, _license_key, _last_validated
+
+    if not key or len(key) < 8:
+        return {"valid": False, "plan": "free", "message": "No license key."}
+
+    # Try live validation
+    try:
+        payload = json.dumps({"key": key, "version": "0.2.0"}).encode()
+        req = urllib.request.Request(
+            VALIDATION_URL,
+            data=payload,
+            headers={"Content-Type": "application/json", "User-Agent": "tokenwatch/0.2.0"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=6) as resp:
+            result = json.loads(resp.read())
+
+        valid = result.get("valid", False)
+        _is_pro        = valid
+        _license_key   = key
+        _last_validated = time.time()
+        _save_cache(key, valid)
+        return {
+            "valid":   valid,
+            "plan":    result.get("plan", "pro" if valid else "free"),
+            "message": result.get("message", ""),
+        }
+
+    except Exception as e:
+        logger.debug(f"License validation offline: {e}")
+
+    # Offline fallback: use cache within grace period
+    cache = _load_cache()
+    if cache.get("key") == key and cache.get("valid"):
+        age = time.time() - cache.get("checked_at", 0)
+        if age < GRACE_PERIOD:
+            _is_pro = True
+            _license_key = key
+            days_left = int((GRACE_PERIOD - age) / 86400)
+            return {
+                "valid":   True,
+                "plan":    "pro",
+                "message": f"Offline — validated from cache ({days_left}d grace remaining).",
+            }
+
+    return {"valid": False, "plan": "free", "message": "Could not validate license (offline)."}
+
+
+def is_pro() -> bool:
+    """Quick check — use this to gate Pro features."""
+    return _is_pro
+
+
+def load_from_config() -> None:
+    """Call on startup — loads key from config and validates silently."""
+    from tokenwatch import config as cfg_module
+    key = cfg_module.load().get("license_key", "")
+    if key:
+        validate(key)
+
+
+def get_status() -> dict:
+    return {
+        "is_pro":      _is_pro,
+        "plan":        "pro" if _is_pro else "free",
+        "key_set":     bool(_license_key),
+        "key_preview": (_license_key[:4] + "…" + _license_key[-4:]) if len(_license_key) >= 8 else "",
+    }
+
+
+# Pro-gated feature list (for the dashboard to show/hide UI)
+PRO_FEATURES = ["weekly_digest", "team_report", "priority_support"]