Metadata-Version: 2.4
Name: rightcom-py-alerts
Version: 1.0.1
Summary: SDK Python pour la gestion des alertes via Parse Server
Home-page: https://gitlab.rightcomtech.com/tech-support/packages/rightcom-py-alerts
Author: ODOUNHEWOU Olatoutou Awếlé Véronique
Author-email: veronique@rightcom.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: python-dateutil>=2.8.2
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# Alert SDK Python

![License: Internal](https://img.shields.io/badge/License-Internal-blue.svg)

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](#-caractéristiques)
- [✅ Prérequis](#-prérequis)
- [📦 Installation](#-installation)
- [⚙️ Configuration](#️-configuration)
- [🚀 Utilisation](#-utilisation)
- [Créer une alerte](#créer-une-alerte)
- [Récupérer les statuts d'alertes](#récupérer-les-statuts-dalertes)
- [📚 API Reference](#-api-reference)
- [⚠️ Gestion des erreurs](#️-gestion-des-erreurs)
- [🧪 Tests](#-tests)
- [📝 Changelog](#-changelog)
- [📄 Licence](#-licence)
- [👤 Auteur](#-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)**
```bash
sudo apt update
sudo apt install -y python3.12-venv
```

**2️⃣ Créer et activer un environnement virtuel**
```bash
python3 -m venv venv
source venv/bin/activate
```

Le prompt doit afficher `(venv)`.

**3️⃣ Mettre à jour les outils Python**
```bash
pip install --upgrade pip setuptools wheel
```

**4️⃣ Installer le SDK depuis PyPI**

➤ Dernière version (stable)
```bash
pip install rightcom-py-alerts
```

➤ Version spécifique
```bash
pip install rightcom-py-alerts==1.0.1
```

**5️⃣ Vérifier l'installation**
```bash
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` :
```env
ALERT_SERVER_URL=https://hontogbo.rightcom.com/rightfocusboard-api
ALERT_API_KEY=votre_api_key
```

**Configuration directe**
```python
from alert_sdk import AlertClient

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

## 🚀 Utilisation
```python
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.
```python
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**
```python
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**
```python
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**
```python
statuses = client.get_user_alert_status()

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

## 📚 API Reference
```python
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
```python
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
```bash
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](LICENSE) pour plus de détails.

## 👤 Auteur

ODOUNHEWOU Véronique
📧 <veronique@rightcom.com>

🔗 [https://gitlab.rightcomtech.com/veronique](https://gitlab.rightcomtech.com/veronique)

Made with ❤️ by Véronique ODOUNHEWOU
