Files

Mr¤KayJayDee a48df5509c feat(webhook): ajout de la fonctionnalité d'envoi de webhooks

- 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

2025-07-10 15:15:12 +02:00

11 KiB

Raw Blame History

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

Cloner le repository

git clone <repository-url>
cd webhooks-trigger

Installer les dépendances
```
npm install
```
Construire le plugin
```
npm run build
```

Installer en mode développeur

streamdeck dev
cd com.mr-kayjaydee.webhooks-trigger.sdPlugin
streamdeck link

Redémarrer le plugin (après modifications)
```
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

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 :

// 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

Vérifier les logs

tail -f com.mr-kayjaydee.webhooks-trigger.sdPlugin/logs/*.log

Mode développement avec auto-restart
```
npm run watch
```
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
Redémarrer après modifications
```
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 :

Activer les logs détaillés
Reproduire le problème
Consulter les logs dans logs/com.mr-kayjaydee.webhooks-trigger.0.log
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 :

Fork le projet
Créer une branche feature (git checkout -b feature/amazing-feature)
Commit avec le format : feat(webhook): description en français
Push vers la branche (git push origin feature/amazing-feature)
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 pour l'excellent SDK
SDPI Components pour les composants UI
La communauté Stream Deck pour les retours et suggestions

11 KiB Raw Blame History