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/