Files
Jannik 665f12a369
Build and Push Docker Image / build-and-push (push) Canceled after 0s
chore(license): standardize on CC0-1.0 and third-party notices
2026-11-18 01:18:15 +01:00

282 lines
15 KiB
Markdown

<p align="center">
<img src="public/favicon.png" alt="TokenWatch Logo" width="128" />
</p>
<h1 align="center">TokenWatch</h1>
<p align="center"><strong>Selbstgehosteter API-Quota- &amp; Limit-Tracker mit Live-Dashboard, 7-Tage-Verlaufsdiagramm und ntfy-Benachrichtigungen.</strong></p>
<p align="center">
<a href="README.md">🇬🇧 English</a> · <a href="LIESMICH.md">🇩🇪 Deutsch</a>
</p>
---
## Ü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/<owner>/<repo>: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.