ObsiViewer/docs/GEMINI/GEMINI_API_VERIFICATION.md

🔐 Système de Vérification de la Clé API Gemini

📋 Vue d'ensemble

Ce système permet de vérifier que la variable d'environnement GEMINI_API_KEY est correctement configurée, testée et fonctionnelle. Il expose un endpoint d'état backend et une interface utilisateur dans la page Paramètres → Intégrations.

---

🎯 États du système

Le système retourne l'un des 4 statuts suivants:

Status Backend	Label UI	Description
NOT_CONFIGURED	❌ Non configurée	La clé API n'est pas définie dans l'environnement serveur
CONFIGURED_UNVERIFIED	⚠️ Configurée (non testée)	La clé est présente mais n'a jamais été testée
WORKING	✅ Fonctionnelle	La clé est valide et fonctionne correctement
INVALID	❌ Invalide / Erreur	La clé ne fonctionne pas (auth, réseau, etc.)

Raisons d'erreur détaillées

Reason	Description	Action recommandée
missing_key	GEMINI_API_KEY non définie	Ajouter la clé dans .env et redémarrer
not_tested	Jamais testée	Cliquer sur "Tester la clé"
ok	Fonctionne correctement	Aucune action requise
auth_error	Clé invalide (401/403)	Vérifier la clé ou en générer une nouvelle
network_error	Timeout ou erreur réseau	Vérifier la connexion internet
rate_limited	Limite atteinte (429)	Attendre avant de retester
unexpected_response	Réponse inattendue	Vérifier les logs serveur

---

⚙️ Configuration

1. Ajouter la clé API

Éditez le fichier .env à la racine du projet:

# Ajoutez cette ligne avec votre vraie clé
GEMINI_API_KEY=votre_clé_api_google_gemini_ici

# Optionnel: personnaliser l'URL de base
# GEMINI_API_BASE=https://generativelanguage.googleapis.com

2. Obtenir une clé API Gemini

1. Allez sur Google AI Studio
2. Connectez-vous avec votre compte Google
3. Cliquez sur "Create API Key"
4. Copiez la clé générée
5. Ajoutez-la dans .env

3. Redémarrer le serveur

# Arrêter le serveur actuel (Ctrl+C)
# Relancer
npm start
# ou
pwsh ./start-dev.ps1

---

🔌 API Backend

GET /api/integrations/gemini/status

Retourne le statut actuel de la clé API.

Réponse (200):

{
  "status": "WORKING",
  "lastCheckedAt": "2025-01-15T14:30:00.000Z",
  "details": {
    "reason": "ok",
    "httpCode": 200
  }
}

Sécurité: La clé API n'est jamais renvoyée au client.

POST /api/integrations/gemini/test

Exécute un test live de la clé API (appel à l'API Gemini).

Réponse (200 - Success):

{
  "status": "WORKING",
  "lastCheckedAt": "2025-01-15T14:31:00.000Z",
  "details": {
    "reason": "ok",
    "httpCode": 200
  }
}

Réponse (429 - Rate Limited):

{
  "status": "WORKING",
  "lastCheckedAt": "2025-01-15T14:30:00.000Z",
  "details": {
    "reason": "rate_limited",
    "httpCode": 429,
    "message": "Veuillez patienter 25 secondes avant de retester",
    "waitSeconds": 25
  }
}

Anti-spam: Maximum 1 test toutes les 30 secondes par IP.

DELETE /api/integrations/gemini/cache (Debug)

Réinitialise le cache du statut.

Réponse (200):

{
  "success": true,
  "message": "Cache réinitialisé"
}

---

🎨 Interface Utilisateur

Accès

1. Ouvrir ObsiViewer dans le navigateur
2. Cliquer sur l'icône ⚙️ (Paramètres)
3. Scroller jusqu'à la section "Integrations"
4. Section "Google Gemini API"

Fonctionnalités

Badge de statut

Le badge affiche l'état actuel avec un code couleur:

• 🔴 Rouge: NOT_CONFIGURED ou INVALID
• 🟡 Ambre: CONFIGURED_UNVERIFIED
• 🟢 Vert: WORKING

Actions disponibles

• 🔄 Rafraîchir: Récupère le statut depuis le serveur (sans test live)
• 🧪 Tester la clé: Exécute un test live de connectivité à l'API Gemini

Messages contextuels

Selon le statut, des callouts informatifs s'affichent:

• NOT_CONFIGURED: Instructions pour ajouter la clé dans .env
• CONFIGURED_UNVERIFIED: Invitation à tester la clé
• WORKING: Confirmation que tout fonctionne
• INVALID: Détails de l'erreur et conseils de résolution

---

🧪 Tests

Tests Backend (Node.js Test Runner)

node --test server/integrations/gemini/gemini.health.service.spec.mjs

Couverture:

• ✅ Status NOT_CONFIGURED (clé manquante)
• ✅ Status CONFIGURED_UNVERIFIED (clé présente, non testée)
• ✅ Status WORKING (cache)
• ✅ Anti-spam (rate limiting)
• ✅ Reset du cache

Tests Frontend (Karma + Jasmine)

npm test -- --include='**/integrations.service.spec.ts'

Couverture:

• ✅ getGeminiStatus() avec différents statuts
• ✅ testGeminiKey() success et erreurs
• ✅ Gestion des erreurs HTTP (401, 429, 500, network)
• ✅ resetGeminiCache()

---

🔒 Sécurité

Bonnes pratiques implémentées

1. Clé jamais exposée: La clé API n'est jamais renvoyée au frontend
2. Rate limiting: Maximum 1 test/30s par IP
3. Timeout: Requêtes API limitées à 8 secondes
4. Logs sécurisés: Seuls les codes HTTP sont loggés, jamais la clé
5. Validation: Vérification stricte des paramètres

⚠️ À NE PAS FAIRE

// ❌ JAMAIS
console.log('API Key:', process.env.GEMINI_API_KEY);

// ❌ JAMAIS
res.json({ apiKey: process.env.GEMINI_API_KEY });

// ❌ JAMAIS
throw new Error(`Invalid key: ${process.env.GEMINI_API_KEY}`);

✅ À FAIRE

// ✅ Bon
console.log('[Gemini] API key is configured');

// ✅ Bon
res.json({ status: 'WORKING' });

// ✅ Bon
throw new Error('Invalid API key (details hidden for security)');

---

🐛 Dépannage

Problème: "Non configurée" malgré la clé dans .env

Causes possibles:

1. Serveur pas redémarré après modification .env
2. Mauvais fichier .env (doit être à la racine, pas dans /docker-compose)
3. Syntaxe incorrecte dans .env (espaces, guillemets)

Solution:

# Vérifier que la clé est bien chargée
node -e "require('dotenv').config(); console.log(process.env.GEMINI_API_KEY ? 'OK' : 'MISSING');"

# Redémarrer le serveur
npm start

Problème: "Invalide / Erreur" avec code 401

Cause: Clé API invalide ou révoquée

Solution:

1. Vérifier la clé sur Google AI Studio
2. Générer une nouvelle clé si nécessaire
3. Mettre à jour .env
4. Redémarrer

Problème: "Trop de requêtes" (429)

Cause: Rate limiting de Google ou anti-spam local

Solution:

• Rate limit Google: Attendre quelques minutes
• Rate limit local: Attendre 30 secondes entre les tests

Problème: Erreur réseau (timeout)

Causes possibles:

1. Pas de connexion internet
2. Proxy/firewall bloque les requêtes vers Google
3. DNS ne résout pas generativelanguage.googleapis.com

Solution:

# Tester la connectivité
curl https://generativelanguage.googleapis.com/v1beta/models?key=VOTRE_CLE

# Si timeout, vérifier proxy/firewall

---

📊 Architecture Technique

Flow Diagram

┌─────────────────┐
│  User clicks    │
│  "Tester"       │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────┐
│  IntegrationsService (Angular)  │
│  POST /api/integrations/gemini/test  │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Express Route Handler          │
│  /api/integrations/gemini/test  │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  GeminiHealthService            │
│  - Check rate limiting          │
│  - Call Gemini API              │
│  - Update cache                 │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Google Gemini API              │
│  GET /v1beta/models             │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────────────────────┐
│  Response → Cache → Frontend    │
│  Badge updated with status      │
└─────────────────────────────────┘

Fichiers Backend

server/integrations/gemini/
├── gemini.types.mjs              # Types JSDoc
├── gemini.health.service.mjs     # Service de vérification
├── gemini.routes.mjs             # Routes Express
└── gemini.health.service.spec.mjs # Tests unitaires

Fichiers Frontend

src/app/
├── services/
│   ├── integrations.types.ts     # Types TypeScript
│   ├── integrations.service.ts   # Service Angular
│   └── integrations.service.spec.ts # Tests Jasmine
└── features/settings/integrations/
    └── settings-integrations-gemini.component.ts # Composant UI

---

🚀 Évolutions Futures

Version 1.1

• Persistance du cache dans SQLite/JSON (survie aux redémarrages)
• Métriques: compteur d'échecs, latence moyenne
• Support de plusieurs clés (rotation automatique)
• Webhook pour alertes d'erreur

Version 1.2

• Test automatique au démarrage du serveur
• Health check périodique (toutes les 5 min)
• Dashboard d'observabilité (Grafana/Prometheus)

---

📞 Support

Liens utiles

• Documentation Gemini API
• Google AI Studio
• Limites et quotas

Problème persistant ?

1. Vérifier les logs serveur:

   # Logs du test
   [GeminiHealth] Testing API key connectivity...
   [GeminiHealth] ✅ API key is WORKING (12 models available)
   
   # ou
   [GeminiHealth] ❌ API key is INVALID (authentication failed)
   

2. Activer le mode debug (optionnel):

   // server/integrations/gemini/gemini.health.service.mjs
   // Ligne ~52: Ajouter des console.log() pour debug
   

3. Créer une issue GitHub avec:

   • Status retourné
   • Logs serveur (sans la clé!)
   • Code HTTP de l'erreur

---

Dernière mise à jour: 2025-01-15
Version: 1.0.0
Auteur: ObsiViewer Team