Alert SDK TypeScript

SDK TypeScript 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 TypeScript
• Gestion centralisée des erreurs
• Compatible Parse Server

✅ Prérequis

• Node.js 14+ (Node.js 18+ recommandé pour utiliser fetch natif)
• 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

npm install @techsupport_rightcom/ts-fb-alerts
# ou
yarn add @techsupport_rightcom/ts-fb-alerts
# ou
pnpm add @techsupport_rightcom/ts-fb-alerts

⚙️ 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

import { AlertClient } from "@techsupport_rightcom/ts-fb-alerts";

const client = new AlertClient(
	"https://hontogbo.rightcom.com/rightfocusboard-api",
	"votre_api_key",
);

🚀 Utilisation

import { AlertClient } from "@techsupport_rightcom/ts-fb-alerts";

const client = new AlertClient(
	"https://hontogbo.rightcom.com/rightfocusboard-api",
	"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.

import {
	AlertClient,
	ValidationError,
	APIError,
} from "@techsupport_rightcom/ts-fb-alerts";

const client = new AlertClient(
	"https://hontogbo.rightcom.com/rightfocusboard-api",
	"votre_api_key",
);

try {
	const response = await client.createAlert({
		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"],
	});

	console.log(`✅ 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)
} catch (error) {
	if (error instanceof ValidationError) {
		console.log(`❌ Erreur de validation : ${error.message}`);
	} else if (error instanceof APIError) {
		console.log(`❌ Erreur API : ${error.message}`);
	}
}

Récupérer les statuts d'alertes

Alertes d'un utilisateur

const statuses = await client.getUserAlertStatus({ userId: "4I58EibC55" });

for (const status of statuses) {
	const readStatus = status.isRead ? "✓ Lue" : "✗ Non lue";
	console.log(`${status.alert.titre} [${readStatus}]`);
	console.log(`  Sévérité: ${status.alert.severite}`);
	console.log(`  Ref: ${status.alert.ref}`);
	console.log(`  Créée le: ${status.createdAt}`);
}

Statuts d'une alerte via sa ref

const statuses = await client.getUserAlertStatus({
	alertRef: "votre-ref-nanoid-ici",
});

for (const status of statuses) {
	console.log(status.user.email, status.isRead);
}

Tous les statuts

const statuses = await client.getUserAlertStatus();

for (const status of statuses) {
	console.log(status.user.email, status.alert.ref, status.isRead);
}

📚 API Reference

new AlertClient(
    serverUrl: string,
    apiKey: string,
    timeout?: number = 30
)

createAlert(options)

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

Retourne : CreateAlertResponse (Promise)

getUserAlertStatus(options?)

| Paramètre | Type | Description | | ---------- | -------- | ------------------------------------ | | userId | string | Filtrer par ID utilisateur Parse | | alertRef | string | Filtrer par ref nanoid de l'alerte |

Retourne : Promise<UserAlertStatus[]>

⚠️ Gestion des erreurs

import {
	ValidationError,
	APIError,
	AuthenticationError,
	AlertSDKError,
} from "@techsupport_rightcom/ts-fb-alerts";

| Exception | Description | | --------------------- | ---------------------------------------------------------------- | | ValidationError | Paramètres manquants ou invalides | | AuthenticationError | api_key manquante ou invalide | | APIError | Erreur retournée par l'API (contient statusCode et response) | | AlertSDKError | Erreur générique du SDK |

🧪 Tests

npm run example
# ou
npx ts-node examples/usage_example.ts

📝 Changelog

v1.0.0

• Portage TypeScript du SDK Python rightcom-py-alerts 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 getUserAlertStatus()
• 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

📄 Licence

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