a48df5509c
- Remplacement de l'action de compteur par une action d'envoi de webhook - Ajout d'une interface utilisateur pour configurer les paramètres du webhook (URL, méthode, headers, corps) - Implémentation des services de validation, de construction de requêtes et d'exécution de requêtes - Ajout de la gestion des erreurs et des messages de validation - Mise à jour du fichier README avec des instructions d'utilisation et des exemples de configuration - Ajout de nouveaux icônes pour l'action d'envoi de webhook
336 lines
11 KiB
Markdown
336 lines
11 KiB
Markdown
# Webhooks Trigger - Stream Deck Plugin
|
|
|
|
Un plugin Stream Deck professionnel pour envoyer des requêtes HTTP webhook en appuyant sur un bouton. Construit avec le SDK officiel Elgato et TypeScript avec une architecture modulaire suivant les principes SOLID.
|
|
|
|
## 🚀 Fonctionnalités
|
|
|
|
- **Requêtes HTTP complètes** : Support de GET, POST, PUT, PATCH, DELETE
|
|
- **Configuration flexible** : URL, headers, body, méthode HTTP personnalisables
|
|
- **Validation JSON intégrée** : Validation en temps réel des headers et body JSON
|
|
- **Beautification JSON** : Formatage automatique du JSON avec indentation
|
|
- **Vérification de configuration** : Bouton de validation complète avec détection d'erreurs
|
|
- **Retour visuel** : Indication de succès/échec sur Stream Deck
|
|
- **Logging complet** : Logs détaillés pour debugging et monitoring
|
|
- **Interface utilisateur moderne** : UI propre avec composants SDPI
|
|
- **Architecture modulaire** : Services séparés suivant les principes DRY et SRP
|
|
|
|
## 📦 Installation
|
|
|
|
### Prérequis
|
|
|
|
- Stream Deck software officiel installé
|
|
- Node.js 20+ et npm
|
|
- Stream Deck CLI (`npm install -g @elgato/cli`)
|
|
|
|
### Installation développeur
|
|
|
|
1. **Cloner le repository**
|
|
|
|
```bash
|
|
git clone <repository-url>
|
|
cd webhooks-trigger
|
|
```
|
|
|
|
2. **Installer les dépendances**
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
3. **Construire le plugin**
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
4. **Installer en mode développeur**
|
|
|
|
```bash
|
|
streamdeck dev
|
|
cd com.mr-kayjaydee.webhooks-trigger.sdPlugin
|
|
streamdeck link
|
|
```
|
|
|
|
5. **Redémarrer le plugin (après modifications)**
|
|
```bash
|
|
npm run restart
|
|
```
|
|
|
|
## ⚙️ Configuration
|
|
|
|
### Champs de configuration
|
|
|
|
| Champ | Description | Requis | Exemple |
|
|
| --------------- | ----------------------------- | ------ | -------------------------------------- |
|
|
| **URL** | URL de destination du webhook | ✅ | `https://webhook.site/abc123` |
|
|
| **HTTP Method** | Méthode HTTP à utiliser | ✅ | `POST` |
|
|
| **Headers** | Headers HTTP au format JSON | ❌ | `{"Content-Type": "application/json"}` |
|
|
| **Body** | Corps de la requête | ❌ | `{"message": "Hello!"}` |
|
|
|
|
> **Note** : Le titre du bouton est géré nativement par Stream Deck via l'interface standard.
|
|
|
|
### Exemples de configuration
|
|
|
|
#### Webhook simple GET
|
|
|
|
```
|
|
URL: https://api.example.com/webhook
|
|
Method: GET
|
|
Headers: {"Authorization": "Bearer token123"}
|
|
Body: (vide)
|
|
```
|
|
|
|
#### Webhook POST avec JSON
|
|
|
|
```
|
|
URL: https://webhook.site/abc123
|
|
Method: POST
|
|
Headers: {"Content-Type": "application/json"}
|
|
Body: {"event": "button_pressed", "timestamp": "now"}
|
|
```
|
|
|
|
#### Notification Discord
|
|
|
|
```
|
|
URL: https://discord.com/api/webhooks/your-webhook-url
|
|
Method: POST
|
|
Headers: {"Content-Type": "application/json"}
|
|
Body: {"content": "Message depuis Stream Deck!"}
|
|
```
|
|
|
|
## 🛠️ Interface utilisateur
|
|
|
|
### Boutons de validation
|
|
|
|
- **Beautify JSON** : Formate automatiquement le JSON avec indentation propre
|
|
- **Validate JSON** : Vérifie la syntaxe JSON et affiche les erreurs
|
|
- **Verify Configuration** : Validation complète de toute la configuration
|
|
|
|
### Messages de validation
|
|
|
|
- **Erreurs** : Affichées en rouge sous les champs pendant 5 secondes
|
|
- **Succès** : Affichées en vert pendant 5 secondes
|
|
- **Validation automatique** : Vérification en temps réel lors de la saisie
|
|
- **Timeouts gérés** : Les timeouts précédents sont automatiquement effacés
|
|
|
|
### Retour visuel Stream Deck
|
|
|
|
- **✅ Checkmark vert** : Requête envoyée avec succès (status 200-299)
|
|
- **❌ X rouge** : Erreur (URL invalide, JSON malformé, erreur réseau)
|
|
|
|
## 📋 Validation et règles
|
|
|
|
### Validation URL
|
|
|
|
- ✅ Protocoles supportés : `http://` et `https://`
|
|
- ✅ Format URL valide requis
|
|
- ❌ URLs relatives non supportées
|
|
|
|
### Validation Headers
|
|
|
|
- ✅ JSON object valide : `{"key": "value"}`
|
|
- ❌ Arrays non supportés : `["value1", "value2"]`
|
|
- ❌ Primitives non supportées : `"string"` ou `123`
|
|
|
|
### Validation Body
|
|
|
|
- ✅ JSON valide ou texte plain
|
|
- ✅ Vide autorisé (optionnel)
|
|
- ⚠️ Warning si body vide pour POST/PUT/PATCH
|
|
- ⚠️ Warning si body présent pour GET
|
|
|
|
### Bonnes pratiques
|
|
|
|
- **Content-Type recommandé** : Ajoutez `{"Content-Type": "application/json"}` pour les requêtes avec body JSON
|
|
- **Headers d'authentification** : Utilisez `{"Authorization": "Bearer token"}` pour l'auth
|
|
- **Validation avant utilisation** : Utilisez le bouton "Verify Configuration" avant la première utilisation
|
|
|
|
## 🔧 Développement
|
|
|
|
### Structure du projet
|
|
|
|
```
|
|
webhooks-trigger/
|
|
├── src/ # Code source TypeScript
|
|
│ ├── actions/
|
|
│ │ └── send-webhook.ts # Action principale du plugin
|
|
│ ├── services/ # Services modulaires (SOLID)
|
|
│ │ ├── validation-service.ts # Service de validation
|
|
│ │ ├── webhook-request-builder.ts # Construction des requêtes HTTP
|
|
│ │ ├── webhook-executor.ts # Exécution des requêtes
|
|
│ │ └── settings-manager.ts # Gestion des paramètres
|
|
│ ├── types/
|
|
│ │ └── webhook-settings.ts # Types TypeScript et constantes
|
|
│ └── plugin.ts # Point d'entrée du plugin
|
|
├── com.mr-kayjaydee.webhooks-trigger.sdPlugin/ # Plugin Stream Deck
|
|
│ ├── manifest.json # Métadonnées du plugin
|
|
│ ├── ui/
|
|
│ │ ├── send-webhook.html # Interface utilisateur
|
|
│ │ └── send-webhook.js # JavaScript frontend
|
|
│ ├── bin/
|
|
│ │ ├── plugin.js # Code compilé (généré)
|
|
│ │ └── package.json # Config module ES (généré)
|
|
│ ├── imgs/ # Icônes et assets
|
|
│ │ ├── actions/send-webhook/ # Icônes de l'action
|
|
│ │ └── plugin/ # Icônes du plugin
|
|
│ └── logs/ # Logs du plugin
|
|
├── package.json # Dépendances et scripts
|
|
├── tsconfig.json # Configuration TypeScript
|
|
└── rollup.config.mjs # Configuration build
|
|
```
|
|
|
|
### Scripts disponibles
|
|
|
|
```bash
|
|
npm run build # Compile TypeScript vers JavaScript
|
|
npm run watch # Mode développement avec watch et auto-restart
|
|
npm run restart # Build + redémarrage du plugin
|
|
```
|
|
|
|
### Architecture logicielle
|
|
|
|
Le plugin suit une architecture modulaire avec les principes **SOLID** :
|
|
|
|
#### **Services Backend (TypeScript)**
|
|
|
|
- **`ValidationService`** : Validation des paramètres webhook
|
|
- **`WebhookRequestBuilder`** : Construction des requêtes HTTP
|
|
- **`WebhookExecutor`** : Exécution des requêtes HTTP
|
|
- **`SettingsManager`** : Gestion et normalisation des paramètres
|
|
|
|
#### **Types et constantes**
|
|
|
|
- **`WebhookSettings`** : Interface TypeScript pour les paramètres
|
|
- **`WEBHOOK_CONSTANTS`** : Constantes partagées (méthodes, protocoles)
|
|
|
|
#### **Frontend (JavaScript)**
|
|
|
|
- Interface utilisateur simple et efficace
|
|
- Validation en temps réel avec gestion des timeouts
|
|
- Beautification JSON intégrée
|
|
- Pas de duplication d'alertes rouge/vert
|
|
|
|
### Logging
|
|
|
|
Le plugin utilise le système de logging du SDK Stream Deck avec des scopes séparés :
|
|
|
|
```typescript
|
|
// Logs disponibles dans : com.mr-kayjaydee.webhooks-trigger.sdPlugin/logs/
|
|
const logger = streamDeck.logger.createScope("SendWebhook");
|
|
logger.info("Message d'information");
|
|
logger.debug("Message de debug");
|
|
logger.error("Message d'erreur");
|
|
```
|
|
|
|
**Localisation des logs** : `com.mr-kayjaydee.webhooks-trigger.sdPlugin/logs/com.mr-kayjaydee.webhooks-trigger.0.log`
|
|
|
|
### Tests et debugging
|
|
|
|
1. **Vérifier les logs**
|
|
|
|
```bash
|
|
tail -f com.mr-kayjaydee.webhooks-trigger.sdPlugin/logs/*.log
|
|
```
|
|
|
|
2. **Mode développement avec auto-restart**
|
|
|
|
```bash
|
|
npm run watch
|
|
```
|
|
|
|
3. **Tester avec webhook.site**
|
|
- Aller sur https://webhook.site
|
|
- Copier l'URL unique générée
|
|
- Configurer le plugin avec cette URL
|
|
- Vérifier les requêtes reçues sur le site
|
|
|
|
4. **Redémarrer après modifications**
|
|
```bash
|
|
npm run restart
|
|
```
|
|
|
|
## 🐛 Dépannage
|
|
|
|
### Problèmes courants
|
|
|
|
**❌ Plugin ne s'installe pas**
|
|
|
|
- Vérifier que Stream Deck software est fermé pendant l'installation
|
|
- Utiliser `streamdeck dev` pour activer le mode développeur
|
|
- Vérifier les permissions du dossier
|
|
|
|
**❌ Requête échoue (X rouge)**
|
|
|
|
- Vérifier l'URL dans un navigateur
|
|
- Valider le JSON des headers/body avec les boutons de validation
|
|
- Consulter les logs pour les détails d'erreur
|
|
- Vérifier la connectivité réseau
|
|
|
|
**❌ Configuration ne se sauvegarde pas**
|
|
|
|
- Vérifier la syntaxe JSON avec les boutons de validation
|
|
- Utiliser le bouton "Verify Configuration"
|
|
- Redémarrer Stream Deck si nécessaire
|
|
|
|
**❌ Bouton reste gris**
|
|
|
|
- Configuration incomplète (URL manquante)
|
|
- JSON headers/body invalide
|
|
- Consulter les logs pour les détails
|
|
|
|
**❌ Build échoue**
|
|
|
|
- Vérifier que Node.js 20+ est installé
|
|
- Supprimer `node_modules` et relancer `npm install`
|
|
- Vérifier les erreurs TypeScript
|
|
|
|
### Support et logs
|
|
|
|
Pour obtenir de l'aide :
|
|
|
|
1. Activer les logs détaillés
|
|
2. Reproduire le problème
|
|
3. Consulter les logs dans `logs/com.mr-kayjaydee.webhooks-trigger.0.log`
|
|
4. Inclure les logs dans votre rapport de bug
|
|
|
|
## 🏗️ Technologies utilisées
|
|
|
|
- **Stream Deck SDK v1.0.0** : SDK officiel Elgato
|
|
- **TypeScript 5.2+** : Langage principal avec typage fort
|
|
- **Node.js 20** : Runtime JavaScript
|
|
- **Rollup** : Bundler pour la compilation
|
|
- **SDPI Components** : Composants UI Stream Deck
|
|
|
|
## 📄 Licence
|
|
|
|
Ce projet est sous licence MIT. Voir le fichier `LICENSE` pour plus de détails.
|
|
|
|
## 🤝 Contribution
|
|
|
|
Les contributions sont les bienvenues ! Merci de :
|
|
|
|
1. Fork le projet
|
|
2. Créer une branche feature (`git checkout -b feature/amazing-feature`)
|
|
3. Commit avec le format : `feat(webhook): description en français`
|
|
4. Push vers la branche (`git push origin feature/amazing-feature`)
|
|
5. Ouvrir une Pull Request
|
|
|
|
### Format des commits
|
|
|
|
```
|
|
type(scope): description en français
|
|
|
|
Types autorisés : feat, fix, docs, refactor, test, chore
|
|
Exemples :
|
|
- feat(validation): ajout de la validation JSON en temps réel
|
|
- fix(ui): correction du bug d'affichage des erreurs
|
|
- docs(readme): mise à jour de la documentation
|
|
- refactor(services): simplification de l'architecture
|
|
```
|
|
|
|
## ✨ Remerciements
|
|
|
|
- [Elgato Stream Deck SDK](https://docs.elgato.com/sdk/) pour l'excellent SDK
|
|
- [SDPI Components](https://sdpi-components.dev/) pour les composants UI
|
|
- La communauté Stream Deck pour les retours et suggestions
|