alert-sdk 1.0.0

SDK Python pour la gestion des alertes via Parse Server

Alert SDK Python

SDK Python pour la gestion des alertes via Parse Server avec traitement asynchrone BullMQ. Il permet de mettre en queue la création d'alertes et de consulter leur statut par utilisateur ou par alerte.

📋 Table des matières

• ✨ Caractéristiques
• ✅ Prérequis
• 📦 Installation
• ⚙️ Configuration
• 🚀 Utilisation
• Créer une alerte
• Récupérer les statuts d'alertes
• 📚 API Reference
• ⚠️ Gestion des erreurs
• 🧪 Tests
• 📝 Changelog
• 📄 Licence
• 👤 Auteur

✨ Caractéristiques

• Création d'alertes via queue BullMQ (traitement asynchrone)
• Référence unique ref (nanoid) retournée immédiatement après mise en queue
• Assignation automatique aux utilisateurs du département Technical Support et/ou rôle admin
• Récupération des statuts d'alertes (par utilisateur ou par ref d'alerte)
• Authentification par api_key
• Modèles typés avec dataclasses
• Gestion centralisée des erreurs
• Compatible Parse Server

✅ Prérequis

• Python 3.8+ (Python 3.12 recommandé)
• Parse Server opérationnel avec les Cloud Functions requises
• Worker BullMQ actif pour le traitement des alertes en queue
• Accès API :
  • SERVER_URL
  • API_KEY

📦 Installation

⚠️ Sur Ubuntu/Debian récents, l'installation de packages Python doit se faire dans un environnement virtuel (venv).

1️⃣ Installer le support venv (si nécessaire)

sudo apt update
sudo apt install -y python3.12-venv

2️⃣ Créer et activer un environnement virtuel

python3 -m venv venv
source venv/bin/activate

Le prompt doit afficher (venv).

3️⃣ Mettre à jour les outils Python

pip install --upgrade pip setuptools wheel

4️⃣ Installer le SDK depuis GitLab

➤ Branche principale (stable)

pip install git+https://gitlab.rightcomtech.com/tech-support/packages/rightcom-py-alerts.git

➤ Branche spécifique

pip install git+https://gitlab.rightcomtech.com/tech-support/packages/rightcom-py-alerts.git@feature/initial-sdk

5️⃣ Vérifier l'installation

python -c "from alert_sdk import AlertClient; print('SDK OK')"

Résultat attendu :

SDK OK

⚙️ Configuration

Variables d'environnement (recommandé)

Créer un fichier .env :

ALERT_SERVER_URL=https://hontogbo.rightcom.com/rightfocusboard-api
ALERT_API_KEY=votre_api_key

Configuration directe

from alert_sdk import AlertClient

client = AlertClient(
    server_url="https://hontogbo.rightcom.com/rightfocusboard-api",
    api_key="votre_api_key"
)

🚀 Utilisation

from alert_sdk import AlertClient

client = AlertClient(
    server_url="https://hontogbo.rightcom.com/rightfocusboard-api",
    api_key="votre_api_key"
)

Créer une alerte

⚡ La création passe par une queue BullMQ. La réponse est immédiate avec une ref unique (nanoid). La création réelle de l'alerte et la notification des utilisateurs sont traitées de façon asynchrone par le worker.

from alert_sdk import AlertClient, ValidationError, APIError

client = AlertClient(
    server_url="https://hontogbo.rightcom.com/rightfocusboard-api",
    api_key="votre_api_key"
)

try:
    response = client.create_alert(
        titre="Incident serveur critique",
        description="Le serveur de production ne répond plus",
        severite="critique",
        statut="active",
        categorie="système",
        source="monitoring-system",
        details="CPU: 100%, Memory: 95%, Disk: 80%",
        tags=["production", "serveur", "urgent"]
    )

    print(f"✅ Alerte mise en queue : {response.ref}")
    # response.ref      → identifiant unique nanoid (disponible immédiatement)
    # response.success  → True si bien mise en queue
    # ⚠️ response.notifiedUsers n'existe plus (traitement asynchrone)

except ValidationError as e:
    print(f"❌ Erreur de validation : {e}")
except APIError as e:
    print(f"❌ Erreur API : {e}")

Récupérer les statuts d'alertes

Alertes d'un utilisateur

statuses = client.get_user_alert_status(user_id="4I58EibC55")

for status in statuses:
    read_status = "✓ Lue" if status.isRead else "✗ Non lue"
    print(f"{status.alert.titre} [{read_status}]")
    print(f"  Sévérité: {status.alert.severite}")
    print(f"  Ref: {status.alert.ref}")
    print(f"  Créée le: {status.createdAt}")

Statuts d'une alerte via sa ref

statuses = client.get_user_alert_status(alert_ref="votre-ref-nanoid-ici")

for status in statuses:
    print(status.user.email, status.isRead)

Tous les statuts

statuses = client.get_user_alert_status()

for status in statuses:
    print(status.user.email, status.alert.ref, status.isRead)

📚 API Reference

AlertClient(
    server_url: str,
    api_key: str,
    timeout: int = 30
)

create_alert()

Paramètre	Type	Obligatoire	Description
titre	str	✅	Titre de l'alerte
description	str	✅	Description de l'alerte
severite	str	✅	critique | élevée | moyenne | faible | info
statut	str	❌	active | résolue | en_cours | ignorée (défaut: active)
categorie	str	❌	système | sécurité | performance | réseau | application | autre
source	str	❌	Source de l'alerte
details	str	❌	Détails supplémentaires
tags	list[str]	❌	Liste de tags

Retourne : CreateAlertResponse(success: bool, ref: str)

get_user_alert_status()

Paramètre	Type	Description
user_id	str	Filtrer par ID utilisateur Parse
alert_ref	str	Filtrer par ref nanoid de l'alerte

Retourne : List[UserAlertStatus]

⚠️ Gestion des erreurs

from alert_sdk import ValidationError, APIError, AuthenticationError, AlertSDKError

Exception	Description
ValidationError	Paramètres manquants ou invalides
AuthenticationError	api_key manquante ou invalide
APIError	Erreur retournée par l'API
AlertSDKError	Erreur générique du SDK

🧪 Tests

cd examples
python3 usage_example.py

📝 Changelog

v2.0.0

• Intégration BullMQ : création d'alertes asynchrone via queue
• alertId remplacé par ref (nanoid) dans CreateAlertResponse
• alert_id remplacé par alert_ref dans get_user_alert_status()
• Suppression de notifiedUsers (traitement asynchrone)
• Ajout du champ ref sur le modèle Alert
• Remplacement de app_id / master_key / session_token par api_key

v1.0.0

• Première version stable
• Création d'alertes
• Lecture des statuts
• Support Master Key / Session Token

📄 Licence

Licence Internal — voir le fichier LICENSE pour plus de détails.

👤 Auteur

ODOUNHEWOU Véronique 📧 [e-mail]

🔗 https://gitlab.rightcomtech.com/veronique

Made with ❤️ by Véronique ODOUNHEWOU