add README

README.md

@@ -0,0 +1,249 @@
+# Codex Reset Alerts 🚀
+
+Petit watcher Node.js qui surveille ton quota **OpenAI Codex** et envoie une notification **ntfy** dès que ton quota est de nouveau disponible.
+
+L'idée est simple : lorsque Codex indique que ton quota est épuisé, tu lances le watcher et tu peux passer à autre chose. Il surveille le quota en arrière-plan, t'envoie une notification lors du reset réel, puis s'arrête automatiquement.
+
+## Fonctionnement
+
+```text
+Quota Codex épuisé 🔴
+        │
+        ▼
+     npm start
+        │
+        ▼
+Codex App Server
+        │
+        ├── account/rateLimits/read
+        │
+        └── account/rateLimits/updated
+        │
+        ▼
+Surveillance du quota
+        │
+        ▼
+Quota disponible 🟢
+        │
+        ▼
+      ntfy
+        │
+        ▼
+📱 Notification
+        │
+        ▼
+   Arrêt du watcher
+```
+
+Le watcher utilise deux mécanismes :
+
+* les événements `account/rateLimits/updated` envoyés par Codex ;
+* un polling périodique comme filet de sécurité.
+
+Le timestamp `resetsAt` fourni par Codex est également surveillé, mais il n'est **pas considéré comme une garantie** : le quota peut être réinitialisé avant la date annoncée.
+
+La notification n'est envoyée que lorsqu'un passage réel de **quota épuisé → quota disponible** est détecté.
+
+## Prérequis
+
+* Linux / WSL
+* Node.js 20+
+* OpenAI Codex CLI
+* un compte ChatGPT connecté dans Codex
+* l'application ntfy sur ton téléphone
+
+## Installation
+
+Clone le dépôt :
+
+```bash
+git clone ssh://git@git.shinuwa.fr:2222/shinuwa/codex-reset-alerts.git
+cd codex-reset-alerts
+```
+
+Installe Codex CLI si nécessaire :
+
+```bash
+npm install -g @openai/codex
+```
+
+Vérifie l'installation :
+
+```bash
+codex --version
+```
+
+Puis lance une première fois Codex pour t'authentifier :
+
+```bash
+codex
+```
+
+## Configuration
+
+Crée un fichier `.env` à la racine :
+
+```env
+NTFY_URL=https://ntfy.sh
+NTFY_TOPIC=mon-topic-secret
+
+POLL_INTERVAL_SECONDS=60
+```
+
+### `NTFY_URL`
+
+Adresse du serveur ntfy.
+
+Par défaut :
+
+```text
+https://ntfy.sh
+```
+
+Tu peux également utiliser une instance ntfy auto-hébergée.
+
+### `NTFY_TOPIC`
+
+Topic sur lequel la notification sera envoyée.
+
+Abonne ton téléphone au même topic dans l'application ntfy.
+
+> Sur un serveur ntfy public, utilise de préférence un nom de topic long et difficile à deviner.
+
+### `POLL_INTERVAL_SECONDS`
+
+Intervalle entre deux vérifications du quota.
+
+Par défaut :
+
+```text
+60 secondes
+```
+
+Les événements envoyés directement par Codex permettent généralement de détecter les changements plus rapidement ; le polling sert principalement de sécurité.
+
+## Utilisation
+
+Lorsque ton quota Codex est épuisé :
+
+```bash
+npm start
+```
+
+Si le quota est effectivement épuisé :
+
+```text
+🔌 Connexion à Codex App Server...
+✅ Connecté.
+
+🔎 Source : démarrage
+📊 Utilisé : 100%
+🔴 État : quota épuisé
+🕒 Reset annoncé : jeudi 20 août 2026 à 13:58:03
+⏳ Temps théorique : 3j 1h 55min
+
+🔴 Quota épuisé.
+👀 Surveillance du reset activée.
+
+👀 Polling toutes les 60s.
+```
+
+Tu peux alors laisser le watcher tourner.
+
+Lorsqu'un reset est détecté :
+
+```text
+🎉 RESET RÉEL DÉTECTÉ !
+📉 100% → 0%
+
+📱 Notification ntfy envoyée.
+✅ Mission terminée.
+👋 Arrêt du watcher.
+```
+
+Tu recevras en parallèle une notification sur ton téléphone :
+
+```text
+🚀 Ton quota Codex est de nouveau disponible !
+
+Avant : 100% utilisé
+Maintenant : 0% utilisé
+```
+
+Le watcher s'arrête ensuite automatiquement.
+
+## Si le quota n'est pas épuisé
+
+Tu peux lancer le programme sans risque :
+
+```bash
+npm start
+```
+
+S'il reste du quota, le watcher ne reste pas inutilement actif :
+
+```text
+📊 Utilisé : 42%
+🟢 État : quota disponible
+
+✅ Ton quota Codex est encore disponible.
+👋 Rien à surveiller, arrêt.
+```
+
+## Tester ntfy
+
+Tu peux vérifier manuellement que ton téléphone reçoit bien les notifications :
+
+```bash
+curl \
+  -H "Title: Test Codex" \
+  -H "Tags: robot" \
+  -d "Hello depuis Codex Reset Alerts 🚀" \
+  https://ntfy.sh/TON_TOPIC
+```
+
+## Lancer le watcher en arrière-plan
+
+Pour éviter de garder ton terminal ouvert, tu peux par exemple utiliser `tmux` :
+
+```bash
+tmux new -s codex-reset
+npm start
+```
+
+Puis détache la session avec :
+
+```text
+Ctrl+B puis D
+```
+
+Pour y retourner :
+
+```bash
+tmux attach -t codex-reset
+```
+
+## Sécurité
+
+Le fichier `.env` ne doit pas être versionné.
+
+Vérifie que `.gitignore` contient :
+
+```gitignore
+.env
+node_modules/
+```
+
+Évite également d'utiliser un nom de topic ntfy facilement devinable si tu utilises le serveur public.
+
+## Pourquoi ?
+
+Parce qu'appuyer sur `/usage` toutes les 20 minutes pour voir si Codex a décidé de rendre du quota, c'est moins amusant que de recevoir :
+
+> 🚀 Codex disponible
+
+et retourner coder.
+
+## Licence
+
+MIT