TokenWatch Logo

TokenWatch

Selbstgehosteter API-Quota- & Limit-Tracker mit Live-Dashboard, 7-Tage-Verlaufsdiagramm und ntfy-Benachrichtigungen.

🇬🇧 English · 🇩🇪 Deutsch

--- ## Überblick **TokenWatch** ist eine selbstgehostete Webanwendung zur zentralen Überwachung von KI-API-Kontingenten und Rate-Limit-Fenstern über mehrere Anbieter hinweg. Die Anwendung fragt externe Provider-APIs ab, empfängt Webhook-Updates eines lokalen Antigravity-Language-Server-Sync-Skripts, speichert Verlaufsdaten in PostgreSQL, stellt interaktive 7-Tage-Verläufe grafisch dar und verschickt automatische Push-Warnungen über **ntfy**, sobald konfigurierte Schwellenwerte überschritten werden. ### Architektur ```text +-----------------------------------+ POST /api/webhook/antigravity | Windows-Host (Antigravity IDE) | -------------------------------------+ | Push-AntigravityQuota.ps1 | | | -> tokenwatch-sync.js | v +-----------------------------------+ +------------------------------+ | TokenWatch-Server (Express) | +-----------------------------------+ REST-API (30-Min- | Port 3000 | | Externe APIs | Cron + Live-Abruf) | - Statische UI (public/) | | - POE (current_balance) | <-------------------> | - /api/quotas | | - MiniMax (coding_plan/remains) | | - /api/history | +-----------------------------------+ +--------------+---------------+ | +----------------------------+----------------------------+ v v +------------------------------+ +------------------------------+ | PostgreSQL-Datenbank | | ntfy-Server | | - quotas (Verlauf) | | Schwellenwert-Warnungen | | - antigravity_latest (JSONB) | +------------------------------+ +------------------------------+ ``` --- ## Funktionen - **Multi-Provider-Quota-Tracking**: - **POE**: Überwacht den aktuellen Punktestand im Verhältnis zum Limit von `2.500.000`, täglichem Refresh (`75.000`), verfallenden Punkten, Tagen bis zum Cap, dem heutigen Tagesverbrauch (berechnet gegen den ersten UTC-Snapshot des Tages) sowie einem Live-Countdown bis 00:00 Uhr UTC. - **MiniMax**: Überwacht `MiniMax (5h)` und `MiniMax (Weekly)` in Prozent (`model_name === 'general'`) inklusive Live-Reset-Countdowns. - **Antigravity (AG)**: Überwacht 5 separate Kontingente per Webhook-Push (`AG Gemini (5h)`, `AG Gemini (Weekly)`, `AG Claude (5h)`, `AG Claude (Weekly)`, `AG Gemini 4 Argon (Weekly)`) inklusive individueller Reset-Zeitstempel (`Heute`, `Morgen` oder Wochentag + Countdown). - **Persistenter Antigravity-Status**: Eingehende Webhook-Daten werden in der PostgreSQL-Tabelle `antigravity_latest` (`JSONB`) gespeichert und beim Serverstart automatisch wiederhergestellt. - **Automatisierte Cron-Snapshots & ntfy-Alerts**: Alle 30 Minuten (`*/30 * * * *`) ruft `node-cron` alle Quotas ab, speichert sie in PostgreSQL und sendet bei Überschreitung von `ALERT_THRESHOLD_PERCENT` (Standard: `80`) eine `ntfy`-Meldung (`Title: TokenWatch Alert`, `Tags: warning,robot`). - **7-Tage-Verlaufsdiagramm**: Interaktives Chart.js-Liniendiagramm, das Datenpunkte in 5-Minuten-Intervallen für `AG Gemini (5h)`, `AG Claude (5h)`, `POE` und `MiniMax (5h)` gruppiert. - **6 wählbare Fortschrittsbalken-Themes**: Live-Wechsel zwischen `Standard`, `Pac-Man`, `Battery`, `Nyan Cat`, `Matrix` und `Lava` (passt auch die Chart.js-Farben dynamisch an). - **Konfetti-Effekt bei 100 %**: Löst bei Erreichen von `100 %` eine `canvas-confetti`-Animation aus und zeigt bei Nicht-POE-Providern `LIMIT REACHED!` an. - **Lokale Antigravity-Sync- & Debug-Werkzeuge**: Enthält `tokenwatch-sync.js`, `Push-AntigravityQuota.ps1` (für die Windows-Aufgabenplanung) sowie das plattformübergreifende Debug-Skript `fetch-quota.js` zum Auslesen der Rohantwort des lokalen Language Servers. --- ## Funktionsweise & Tech-Stack ### Interner Ablauf 1. **Serverstart (`src/server.ts`)**: Startet Express auf `0.0.0.0:3000`, liefert statische Dateien aus `public/` aus, initialisiert die PostgreSQL-Tabellen (`quotas` und `antigravity_latest`) über `initDb()` und lädt gespeicherte Antigravity-Werte über `initAntigravityFromDb()`. 2. **Quota-Abruf (`src/services/providers.ts`)**: - `fetchPoeQuota()` fragt `https://api.poe.com/usage/current_balance` ab. - `fetchMinimaxQuota()` fragt `https://api.minimax.io/v1/api/openplatform/coding_plan/remains` ab. - `fetchAntigravityQuota()` liest den In-Memory-`antigravityCache`, der über `POST /api/webhook/antigravity` aktualisiert oder beim Start aus PostgreSQL geladen wird. 3. **Alert-Logik (`src/cron.ts` & `src/services/ntfy.ts`)**: - Bei **POE** (hier steht `percentage` für das *verbleibende* Kontingent) wird gewarnt, wenn `percentage <= (100 - ALERT_THRESHOLD_PERCENT)` (Standard: `<= 20 %` verbleibend). - Bei **MiniMax** und **Antigravity** (hier steht `percentage` für das *verbrauchte* Kontingent) wird gewarnt, wenn `percentage >= ALERT_THRESHOLD_PERCENT` (Standard: `>= 80 %` verbraucht). 4. **Lokaler Antigravity-Sync (`tokenwatch-sync.js`)**: Sucht laufende `language_server*`-Prozesse über PowerShell (`Get-CimInstance Win32_Process`), liest `--csrf_token` und `--extension_server_port` aus, ermittelt offene Loopback-Ports (`Get-NetTCPConnection` mit `netstat -ano` als Fallback), ruft `POST /exa.language_server_pb.LanguageServerService/RetrieveUserQuotaSummary` auf und sendet die extrahierten Werte an `/api/webhook/antigravity`. ### Tech-Stack & Ports | Komponente | Technologie / Version | Details | | :--- | :--- | :--- | | Laufzeitumgebung | Node.js 24 (`node:24-alpine`) | CommonJS-TypeScript-Build (`tsc` -> `dist/`) | | Backend | Express `^5.2.1`, TypeScript `^7.0.2` | REST-API + Auslieferung statischer Dateien | | Scheduler | `node-cron` `^4.6.0` | Läuft alle 30 Minuten (`*/30 * * * *`) | | HTTP-Client | `axios` `^1.20.0` | Provider-API-Abfragen & ntfy-Alerts | | Datenbank | PostgreSQL (`postgres:15-alpine`, `pg` `^8.23.0`) | Tabellen: `quotas`, `antigravity_latest` | | Frontend | Natives HTML/CSS/JS, Chart.js, `canvas-confetti` | Ausgeliefert aus `public/` | | Standard-Port | `3000` (Container) / `3500` (Jannik-Cloud-Host-Bind) | Konfigurierbar über `PORT` | --- ## Voraussetzungen & Installation ### Voraussetzungen - **Lokale Entwicklung**: Node.js (v20+ / v24 empfohlen), npm und eine laufende PostgreSQL-Instanz. - **Docker-Deployment**: Docker und Docker Compose. - **Antigravity-Sync (optional)**: Windows-Rechner mit laufender Antigravity IDE, Node.js und PowerShell. ### Lokale Installation 1. Repository klonen: ```bash git clone https://git.orfel.de/Jannik/TokenWatch.git cd TokenWatch ``` 2. Abhängigkeiten installieren: ```bash npm install ``` 3. Umgebungsdatei aus `.env.example` erstellen: ```bash cp .env.example .env ``` Danach PostgreSQL-Zugangsdaten, `NTFY_URL` und API-Keys in `.env` eintragen. 4. Im Entwicklungsmodus (`tsx`) starten oder für Produktion bauen: ```bash # Entwicklung npm run dev # Produktions-Build & Start npm run build npm start ``` ### Docker-Compose-Setup TokenWatch gemeinsam mit PostgreSQL (`postgres:15-alpine`) starten: ```bash cp .env.example .env # .env mit Zugangsdaten und API-Keys ausfüllen docker compose up -d ``` Das Dashboard ist anschließend unter `http://localhost:3000` erreichbar. ### Jannik-Cloud-Produktivdeployment Eine fertige Deployment-Vorlage liegt in [`deployment-template/`](deployment-template/README.md): 1. Den Inhalt von `deployment-template/` in das Verzeichnis `services/tokenwatch/` im `Jannik-Cloud`-Repository kopieren. 2. In `services/tokenwatch/` das Skript `bash generate-env.sh` ausführen, um zufällige PostgreSQL-Zugangsdaten zu generieren und optional `.env` nach `.env.age` zu verschlüsseln (über `keys/age-public-key.txt`). 3. Bei Bedarf Provider-API-Keys (`POE_API_KEY`, `MINIMAX_API_KEY` usw.) ergänzen. 4. `tokenwatch.caddy` konfiguriert den Reverse-Proxy für `tw.orfel.de`, `token.orfel.de` und `tokenwatch.orfel.de` auf `tokenwatch:3000`; `docker-compose.yml` bindet `127.0.0.1:3500:3000` im externen Netzwerk `jannik-cloud-net`. 5. Hinweis: `.github/workflows/docker.yml` enthält zudem einen GitHub-Actions-Workflow, der bei Pushes auf `main` oder `master` ein Image nach `ghcr.io//:latest` baut und pusht. --- ## Konfiguration ### Umgebungsvariablen (`.env.example`) | Variable | Beschreibung | Standard / Beispiel | | :--- | :--- | :--- | | `PORT` | HTTP-Server-Port | `3000` | | `DB_USER` | PostgreSQL-Benutzername | `postgres` | | `DB_HOST` | PostgreSQL-Hostname | `postgres` | | `DB_NAME` | Name der PostgreSQL-Datenbank | `tokenwatch` | | `DB_PASSWORD` | PostgreSQL-Passwort | `your_db_password` | | `DB_PORT` | PostgreSQL-Port | `5432` | | `NTFY_URL` | ntfy-Topic-URL für Schwellenwert-Alerts | `https://ntfy.orfel.de/Token-Watch` (Fallback in `ntfy.ts`: `https://ntfy.orfel.de/tokenwatch_dummy`) | | `ALERT_THRESHOLD_PERCENT` | Schwellenwert in Prozent (`>=` verbraucht bzw. `<= 100 - N` verbleibend bei POE) | `80` | | `POE_API_KEY` | Bearer-Token für `api.poe.com/usage/current_balance` | — | | `MINIMAX_API_KEY` | Bearer-Token für `api.minimax.io/v1/api/openplatform/coding_plan/remains` | — | | `ANTIGRAVITY_API_KEY` | Optionaler Platzhalter in `.env.example` / Compose | — | | `ANTIGRAVITY_ENDPOINT` | Optionaler Platzhalter in `.env.example` / Compose | `https://api.antigravity.google/v1/quota` | ### Docker-Volumes - `pgdata:/var/lib/postgresql/data` — Persistiert in `docker-compose.yml` den Verlauf in `quotas` sowie den Zustand in `antigravity_latest`. --- ## Nutzung ### Web-Dashboard Öffne `http://localhost:3000` (bzw. deine konfigurierte Domain), um: - Aktuelle Fortschrittsbalken, Reset-Zeiten (`Heute`/`Morgen`/Wochentag) und Countdowns für POE, Antigravity und MiniMax anzuzeigen. - Über das Dropdown **Progress Bar Style** zwischen 6 Designs zu wechseln: 1. `Standard` 2. `Pac-Man` 3. `Battery` 4. `Nyan Cat` 5. `Matrix` 6. `Lava` - Den 7-Tage-Verlauf im Chart.js-Bereich **History** zu verfolgen. ### API-Endpunkte | Methode | Endpunkt | Beschreibung | | :--- | :--- | :--- | | `GET` | `/api/quotas` | Liefert die aktuellen Quota-Objekte aller Provider inklusive `meta.todayUsed` für POE. | | `GET` | `/api/history` | Liefert die letzten 7 Tage aus der PostgreSQL-Tabelle `quotas` in chronologischer Reihenfolge. | | `POST` | `/api/webhook/antigravity` | Aktualisiert die 5 Antigravity-Einträge im Speicher und persistiert sie in `antigravity_latest`. | Beispiel-Payload für `POST /api/webhook/antigravity`: ```json { "gemini_5h_remaining": 85, "gemini_weekly_remaining": 90, "claude_5h_remaining": 100, "claude_weekly_remaining": 75, "gemini_argon_weekly_remaining": 100, "gemini_5h_reset": "2026-01-01T15:00:00Z", "gemini_weekly_reset": "2026-01-07T00:00:00Z", "claude_5h_reset": null, "claude_weekly_reset": null, "gemini_argon_weekly_reset": null } ``` ### Lokaler Antigravity-Sync (Windows) 1. Stelle sicher, dass `url` in `tokenwatch-sync.js` auf deine TokenWatch-Instanz zeigt (Standard: `https://tokenwatch.orfel.de/api/webhook/antigravity`). 2. Manuell ausführen: ```powershell .\Push-AntigravityQuota.ps1 ``` Oder direkt per Node: ```bash node tokenwatch-sync.js ``` 3. **Automatisierung über Windows-Aufgabenplanung**: - Trigger: Alle 30 Minuten - Aktion: Programm starten - Programm: `powershell` - Argumente: `-ExecutionPolicy Bypass -File "C:\GitHub\TokenWatch\Push-AntigravityQuota.ps1"` 4. **Rohdaten des Language Servers debuggen**: ```bash node fetch-quota.js ``` Fragt `/exa.language_server_pb.LanguageServerService/GetUserStatus` beim lokalen Language Server ab (unterstützt Windows, macOS und Linux) und gibt die vollständige JSON-Antwort aus. --- ## Projektstruktur ```text TokenWatch/ ├── .github/ │ └── workflows/ │ └── docker.yml # GitHub-Actions-Workflow zum Bauen/Pushen nach ghcr.io ├── deployment-template/ │ ├── README.md # Deployment-Anleitung für Jannik-Cloud │ ├── docker-compose.yml # Produktives Compose mit jannik-cloud-net │ ├── generate-env.sh # Erzeugt DB-Passwörter & optional .env.age │ ├── service.enabled # Aktivierungsdatei für Jannik-Cloud │ └── tokenwatch.caddy # Caddy-Reverse-Proxy-Konfiguration ├── public/ │ ├── logos/ # Provider-.ico-Dateien │ ├── app.js # Frontend-Logik, Countdowns, Chart.js & Themes │ ├── favicon.png # TokenWatch-Logo & Favicon │ ├── index.html # Dashboard-HTML │ ├── logo-*.png / .ico / .svg # Provider-Icons (POE, Gemini, Claude, MiniMax, AG) │ └── style.css # Dark-UI & 6 Fortschrittsbalken-Themes ├── src/ │ ├── services/ │ │ ├── db.ts # PostgreSQL-Pool, Tabellen-Init, Verlauf & AG-Persistenz │ │ ├── ntfy.ts # ntfy-Benachrichtigungen │ │ └── providers.ts # POE-, MiniMax- & Antigravity-Provider-Logik │ ├── cron.ts # 30-Minuten-Cron-Job & Schwellenwert-Prüfung │ └── server.ts # Express-App & REST-API-Endpunkte ├── .env.example # Beispiel-Umgebungsvariablen ├── Dockerfile # Node-24-Alpine-Container mit TypeScript-Build ├── docker-compose.yml # Lokales/Standalone-Compose mit PostgreSQL 15 ├── fetch-quota.js # Plattformübergreifendes Debug-Skript für Language Server ├── language-server-process-utils.js# Prozesssuche & CLI-Argument-Extraktion ├── package.json # Abhängigkeiten und npm-Skripte ├── Push-AntigravityQuota.ps1 # PowerShell-Wrapper für Windows-Aufgabenplanung ├── tokenwatch-sync.js # Lokaler Antigravity-Language-Server -> Webhook-Sync └── tsconfig.json # TypeScript-Konfiguration ``` --- ## Lizenz Der eigene Quellcode und die Konfiguration dieses Projekts stehen unter **CC0 1.0 Universal** (Public Domain) — Details in [`LICENSE`](LICENSE). Externe Abhängigkeiten, die über Paketmanager oder Docker-Images installiert werden, behalten ihre jeweiligen eigenen Open-Source-Lizenzen.