docs(readme): mise à jour de la documentation en anglais
- Traduction du README en anglais pour une meilleure accessibilité - Mise à jour des sections sur les fonctionnalités, l'installation, la configuration et le dépannage - Amélioration de la clarté des instructions et des exemples de configuration - Ajout de détails sur la gestion des erreurs et les meilleures pratiques
This commit is contained in:
Mr¤KayJayDee
352
README.md
352
README.md
@@ -1,49 +1,48 @@
|
|||||||
# Webhooks Trigger - Stream Deck Plugin
|
# 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.
|
A professional Stream Deck plugin for sending HTTP webhook requests with the press of a button. Built with TypeScript and the official Elgato Stream Deck SDK.
|
||||||
|
|
||||||
## 🚀 Fonctionnalités
|
## 🚀 Features
|
||||||
|
|
||||||
- **Requêtes HTTP complètes** : Support de GET, POST, PUT, PATCH, DELETE
|
- **Complete HTTP Support**: GET, POST, PUT, PATCH, DELETE methods
|
||||||
- **Configuration flexible** : URL, headers, body, méthode HTTP personnalisables
|
- **Flexible Configuration**: Customizable URL, headers, body, and HTTP method
|
||||||
- **Validation JSON intégrée** : Validation en temps réel des headers et body JSON
|
- **JSON Validation**: Real-time validation of headers and body JSON
|
||||||
- **Beautification JSON** : Formatage automatique du JSON avec indentation
|
- **JSON Beautification**: Automatic JSON formatting with proper indentation
|
||||||
- **Vérification de configuration** : Bouton de validation complète avec détection d'erreurs
|
- **Configuration Verification**: Complete validation with error detection
|
||||||
- **Retour visuel** : Indication de succès/échec sur Stream Deck
|
- **Visual Feedback**: Success/failure indication directly on Stream Deck
|
||||||
- **Logging complet** : Logs détaillés pour debugging et monitoring
|
- **Comprehensive Logging**: Detailed logs for debugging and monitoring
|
||||||
- **Interface utilisateur moderne** : UI propre avec composants SDPI
|
- **Modern UI**: Clean interface with SDPI components
|
||||||
- **Architecture modulaire** : Services séparés suivant les principes DRY et SRP
|
|
||||||
|
|
||||||
## 📦 Installation
|
## 📦 Installation
|
||||||
|
|
||||||
### Prérequis
|
### Prerequisites
|
||||||
|
|
||||||
- Stream Deck software officiel installé
|
- Official Stream Deck software installed
|
||||||
- Node.js 20+ et npm
|
- Node.js 20+ and npm
|
||||||
- Stream Deck CLI (`npm install -g @elgato/cli`)
|
- Stream Deck CLI (`npm install -g @elgato/cli`)
|
||||||
|
|
||||||
### Installation développeur
|
### Developer Installation
|
||||||
|
|
||||||
1. **Cloner le repository**
|
1. **Clone the repository**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone <repository-url>
|
git clone <repository-url>
|
||||||
cd webhooks-trigger
|
cd webhooks-trigger
|
||||||
```
|
```
|
||||||
|
|
||||||
2. **Installer les dépendances**
|
2. **Install dependencies**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm install
|
npm install
|
||||||
```
|
```
|
||||||
|
|
||||||
3. **Construire le plugin**
|
3. **Build the plugin**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run build
|
npm run build
|
||||||
```
|
```
|
||||||
|
|
||||||
4. **Installer en mode développeur**
|
4. **Install in development mode**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
streamdeck dev
|
streamdeck dev
|
||||||
@@ -51,36 +50,36 @@ Un plugin Stream Deck professionnel pour envoyer des requêtes HTTP webhook en a
|
|||||||
streamdeck link
|
streamdeck link
|
||||||
```
|
```
|
||||||
|
|
||||||
5. **Redémarrer le plugin (après modifications)**
|
5. **Restart the plugin (after modifications)**
|
||||||
```bash
|
```bash
|
||||||
npm run restart
|
npm run restart
|
||||||
```
|
```
|
||||||
|
|
||||||
## ⚙️ Configuration
|
## ⚙️ Configuration
|
||||||
|
|
||||||
### Champs de configuration
|
### Configuration Fields
|
||||||
|
|
||||||
| Champ | Description | Requis | Exemple |
|
| Field | Description | Required | Example |
|
||||||
| --------------- | ----------------------------- | ------ | -------------------------------------- |
|
| --------------- | --------------------------- | -------- | -------------------------------------- |
|
||||||
| **URL** | URL de destination du webhook | ✅ | `https://webhook.site/abc123` |
|
| **URL** | Webhook destination URL | ✅ | `https://webhook.site/abc123` |
|
||||||
| **HTTP Method** | Méthode HTTP à utiliser | ✅ | `POST` |
|
| **HTTP Method** | HTTP method to use | ✅ | `POST` |
|
||||||
| **Headers** | Headers HTTP au format JSON | ❌ | `{"Content-Type": "application/json"}` |
|
| **Headers** | HTTP headers in JSON format | ❌ | `{"Content-Type": "application/json"}` |
|
||||||
| **Body** | Corps de la requête | ❌ | `{"message": "Hello!"}` |
|
| **Body** | Request body content | ❌ | `{"message": "Hello!"}` |
|
||||||
|
|
||||||
> **Note** : Le titre du bouton est géré nativement par Stream Deck via l'interface standard.
|
> **Note**: Button title is managed natively by Stream Deck through the standard interface.
|
||||||
|
|
||||||
### Exemples de configuration
|
### Configuration Examples
|
||||||
|
|
||||||
#### Webhook simple GET
|
#### Simple GET Webhook
|
||||||
|
|
||||||
```
|
```
|
||||||
URL: https://api.example.com/webhook
|
URL: https://api.example.com/webhook
|
||||||
Method: GET
|
Method: GET
|
||||||
Headers: {"Authorization": "Bearer token123"}
|
Headers: {"Authorization": "Bearer token123"}
|
||||||
Body: (vide)
|
Body: (empty)
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Webhook POST avec JSON
|
#### POST Webhook with JSON
|
||||||
|
|
||||||
```
|
```
|
||||||
URL: https://webhook.site/abc123
|
URL: https://webhook.site/abc123
|
||||||
@@ -89,247 +88,162 @@ Headers: {"Content-Type": "application/json"}
|
|||||||
Body: {"event": "button_pressed", "timestamp": "now"}
|
Body: {"event": "button_pressed", "timestamp": "now"}
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Notification Discord
|
#### Discord Notification
|
||||||
|
|
||||||
```
|
```
|
||||||
URL: https://discord.com/api/webhooks/your-webhook-url
|
URL: https://discord.com/api/webhooks/your-webhook-url
|
||||||
Method: POST
|
Method: POST
|
||||||
Headers: {"Content-Type": "application/json"}
|
Headers: {"Content-Type": "application/json"}
|
||||||
Body: {"content": "Message depuis Stream Deck!"}
|
Body: {"content": "Message from Stream Deck!"}
|
||||||
```
|
```
|
||||||
|
|
||||||
## 🛠️ Interface utilisateur
|
## 🛠️ User Interface
|
||||||
|
|
||||||
### Boutons de validation
|
### Validation Buttons
|
||||||
|
|
||||||
- **Beautify JSON** : Formate automatiquement le JSON avec indentation propre
|
- **Beautify JSON**: Automatically formats JSON with proper indentation
|
||||||
- **Validate JSON** : Vérifie la syntaxe JSON et affiche les erreurs
|
- **Validate JSON**: Checks JSON syntax and displays errors
|
||||||
- **Verify Configuration** : Validation complète de toute la configuration
|
- **Verify Configuration**: Complete validation of all configuration settings
|
||||||
|
|
||||||
### Messages de validation
|
### Validation Messages
|
||||||
|
|
||||||
- **Erreurs** : Affichées en rouge sous les champs pendant 5 secondes
|
- **Errors**: Displayed in red below fields for 5 seconds
|
||||||
- **Succès** : Affichées en vert pendant 5 secondes
|
- **Success**: Displayed in green for 5 seconds
|
||||||
- **Validation automatique** : Vérification en temps réel lors de la saisie
|
- **Real-time Validation**: Automatic verification during input
|
||||||
- **Timeouts gérés** : Les timeouts précédents sont automatiquement effacés
|
- **Timeout Management**: Previous timeouts are automatically cleared
|
||||||
|
|
||||||
### Retour visuel Stream Deck
|
### Stream Deck Visual Feedback
|
||||||
|
|
||||||
- **✅ Checkmark vert** : Requête envoyée avec succès (status 200-299)
|
- **✅ Green Checkmark**: Request sent successfully (status 200-299)
|
||||||
- **❌ X rouge** : Erreur (URL invalide, JSON malformé, erreur réseau)
|
- **❌ Red X**: Error occurred (invalid URL, malformed JSON, network error)
|
||||||
|
|
||||||
## 📋 Validation et règles
|
## 📋 Validation Rules
|
||||||
|
|
||||||
### Validation URL
|
### URL Validation
|
||||||
|
|
||||||
- ✅ Protocoles supportés : `http://` et `https://`
|
- ✅ Supported protocols: `http://` and `https://`
|
||||||
- ✅ Format URL valide requis
|
- ✅ Valid URL format required
|
||||||
- ❌ URLs relatives non supportées
|
- ❌ Relative URLs not supported
|
||||||
|
|
||||||
### Validation Headers
|
### Headers Validation
|
||||||
|
|
||||||
- ✅ JSON object valide : `{"key": "value"}`
|
- ✅ Valid JSON object: `{"key": "value"}`
|
||||||
- ❌ Arrays non supportés : `["value1", "value2"]`
|
- ❌ Arrays not supported: `["value1", "value2"]`
|
||||||
- ❌ Primitives non supportées : `"string"` ou `123`
|
- ❌ Primitives not supported: `"string"` or `123`
|
||||||
|
|
||||||
### Validation Body
|
### Body Validation
|
||||||
|
|
||||||
- ✅ JSON valide ou texte plain
|
- ✅ Valid JSON or plain text
|
||||||
- ✅ Vide autorisé (optionnel)
|
- ✅ Empty allowed (optional)
|
||||||
- ⚠️ Warning si body vide pour POST/PUT/PATCH
|
- ⚠️ Warning if body is empty for POST/PUT/PATCH
|
||||||
- ⚠️ Warning si body présent pour GET
|
- ⚠️ Warning if body is present for GET
|
||||||
|
|
||||||
### Bonnes pratiques
|
### Best Practices
|
||||||
|
|
||||||
- **Content-Type recommandé** : Ajoutez `{"Content-Type": "application/json"}` pour les requêtes avec body JSON
|
- **Content-Type Recommended**: Add `{"Content-Type": "application/json"}` for JSON body requests
|
||||||
- **Headers d'authentification** : Utilisez `{"Authorization": "Bearer token"}` pour l'auth
|
- **Authentication Headers**: Use `{"Authorization": "Bearer token"}` for authentication
|
||||||
- **Validation avant utilisation** : Utilisez le bouton "Verify Configuration" avant la première utilisation
|
- **Pre-validation**: Use "Verify Configuration" button before first use
|
||||||
|
|
||||||
## 🔧 Développement
|
## 🔧 Development
|
||||||
|
|
||||||
### Structure du projet
|
### Project Structure
|
||||||
|
|
||||||
```
|
```
|
||||||
webhooks-trigger/
|
webhooks-trigger/
|
||||||
├── src/ # Code source TypeScript
|
├── src/ # TypeScript source code
|
||||||
│ ├── actions/
|
│ ├── actions/
|
||||||
│ │ └── send-webhook.ts # Action principale du plugin
|
│ │ └── send-webhook.ts # Main plugin action
|
||||||
│ ├── services/ # Services modulaires (SOLID)
|
│ ├── services/ # Service modules
|
||||||
│ │ ├── validation-service.ts # Service de validation
|
│ │ ├── validation-service.ts # Validation logic
|
||||||
│ │ ├── webhook-request-builder.ts # Construction des requêtes HTTP
|
│ │ ├── webhook-request-builder.ts # HTTP request construction
|
||||||
│ │ ├── webhook-executor.ts # Exécution des requêtes
|
│ │ ├── webhook-executor.ts # Request execution
|
||||||
│ │ └── settings-manager.ts # Gestion des paramètres
|
│ │ └── settings-manager.ts # Settings management
|
||||||
│ ├── types/
|
│ ├── types/
|
||||||
│ │ └── webhook-settings.ts # Types TypeScript et constantes
|
│ │ └── webhook-settings.ts # TypeScript types and constants
|
||||||
│ └── plugin.ts # Point d'entrée du plugin
|
│ └── plugin.ts # Plugin entry point
|
||||||
├── com.mr-kayjaydee.webhooks-trigger.sdPlugin/ # Plugin Stream Deck
|
├── com.mr-kayjaydee.webhooks-trigger.sdPlugin/ # Stream Deck plugin
|
||||||
│ ├── manifest.json # Métadonnées du plugin
|
│ ├── manifest.json # Plugin metadata
|
||||||
│ ├── ui/
|
│ ├── ui/
|
||||||
│ │ ├── send-webhook.html # Interface utilisateur
|
│ │ ├── send-webhook.html # User interface
|
||||||
│ │ └── send-webhook.js # JavaScript frontend
|
│ │ └── send-webhook.js # Frontend JavaScript
|
||||||
│ ├── bin/
|
│ ├── bin/
|
||||||
│ │ ├── plugin.js # Code compilé (généré)
|
│ │ ├── plugin.js # Compiled code (generated)
|
||||||
│ │ └── package.json # Config module ES (généré)
|
│ │ └── package.json # ES module config (generated)
|
||||||
│ ├── imgs/ # Icônes et assets
|
│ └── imgs/ # Icons and assets
|
||||||
│ │ ├── actions/send-webhook/ # Icônes de l'action
|
├── package.json # Dependencies and scripts
|
||||||
│ │ └── plugin/ # Icônes du plugin
|
├── tsconfig.json # TypeScript configuration
|
||||||
│ └── logs/ # Logs du plugin
|
└── rollup.config.mjs # Build configuration
|
||||||
├── package.json # Dépendances et scripts
|
|
||||||
├── tsconfig.json # Configuration TypeScript
|
|
||||||
└── rollup.config.mjs # Configuration build
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Scripts disponibles
|
### Available Scripts
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npm run build # Compile TypeScript vers JavaScript
|
npm run build # Compile TypeScript to JavaScript
|
||||||
npm run watch # Mode développement avec watch et auto-restart
|
npm run watch # Development mode with watch and auto-restart
|
||||||
npm run restart # Build + redémarrage du plugin
|
npm run restart # Build + restart plugin
|
||||||
```
|
```
|
||||||
|
|
||||||
### Architecture logicielle
|
### HTTP Methods
|
||||||
|
|
||||||
Le plugin suit une architecture modulaire avec les principes **SOLID** :
|
- **GET**: Retrieve data from the server
|
||||||
|
- **POST**: Send data to create new resources
|
||||||
|
- **PUT**: Update or create resources
|
||||||
|
- **PATCH**: Partially update resources
|
||||||
|
- **DELETE**: Remove resources
|
||||||
|
|
||||||
#### **Services Backend (TypeScript)**
|
### Error Handling
|
||||||
|
|
||||||
- **`ValidationService`** : Validation des paramètres webhook
|
The plugin handles various error scenarios:
|
||||||
- **`WebhookRequestBuilder`** : Construction des requêtes HTTP
|
|
||||||
- **`WebhookExecutor`** : Exécution des requêtes HTTP
|
|
||||||
- **`SettingsManager`** : Gestion et normalisation des paramètres
|
|
||||||
|
|
||||||
#### **Types et constantes**
|
- **Network Errors**: Connection timeouts, DNS resolution failures
|
||||||
|
- **HTTP Errors**: 4xx and 5xx status codes
|
||||||
|
- **Validation Errors**: Invalid JSON, malformed URLs
|
||||||
|
- **Configuration Errors**: Missing required fields
|
||||||
|
|
||||||
- **`WebhookSettings`** : Interface TypeScript pour les paramètres
|
## 🚨 Troubleshooting
|
||||||
- **`WEBHOOK_CONSTANTS`** : Constantes partagées (méthodes, protocoles)
|
|
||||||
|
|
||||||
#### **Frontend (JavaScript)**
|
### Common Issues
|
||||||
|
|
||||||
- Interface utilisateur simple et efficace
|
1. **Plugin Not Appearing**
|
||||||
- Validation en temps réel avec gestion des timeouts
|
- Ensure Stream Deck software is running
|
||||||
- Beautification JSON intégrée
|
- Check if plugin is properly linked with `streamdeck link`
|
||||||
- Pas de duplication d'alertes rouge/vert
|
- Restart Stream Deck software
|
||||||
|
|
||||||
### Logging
|
2. **Webhook Not Sending**
|
||||||
|
- Verify URL is accessible
|
||||||
|
- Check network connectivity
|
||||||
|
- Validate JSON syntax in headers/body
|
||||||
|
- Review Stream Deck logs
|
||||||
|
|
||||||
Le plugin utilise le système de logging du SDK Stream Deck avec des scopes séparés :
|
3. **JSON Validation Errors**
|
||||||
|
- Use the "Beautify JSON" button to format
|
||||||
|
- Check for missing quotes, commas, or brackets
|
||||||
|
- Ensure headers are objects, not arrays
|
||||||
|
|
||||||
```typescript
|
### Debug Logging
|
||||||
// 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`
|
The plugin includes comprehensive logging. To view logs:
|
||||||
|
|
||||||
### Tests et debugging
|
1. Open Stream Deck software
|
||||||
|
2. Go to preferences → Advanced → Enable debug logging
|
||||||
|
3. Check the plugin logs directory
|
||||||
|
|
||||||
1. **Vérifier les logs**
|
## 📄 License
|
||||||
|
|
||||||
```bash
|
This project is licensed under the MIT License.
|
||||||
tail -f com.mr-kayjaydee.webhooks-trigger.sdPlugin/logs/*.log
|
|
||||||
```
|
|
||||||
|
|
||||||
2. **Mode développement avec auto-restart**
|
## 👤 Author
|
||||||
|
|
||||||
```bash
|
**Mr-KayJayDee**
|
||||||
npm run watch
|
|
||||||
```
|
|
||||||
|
|
||||||
3. **Tester avec webhook.site**
|
## 🤝 Contributing
|
||||||
- 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**
|
Contributions are welcome! Please feel free to submit a Pull Request.
|
||||||
```bash
|
|
||||||
npm run restart
|
|
||||||
```
|
|
||||||
|
|
||||||
## 🐛 Dépannage
|
## 📊 System Requirements
|
||||||
|
|
||||||
### Problèmes courants
|
- **Stream Deck Software**: 6.5 or higher
|
||||||
|
- **Operating System**:
|
||||||
**❌ Plugin ne s'installe pas**
|
- Windows 10 or higher
|
||||||
|
- macOS 12 or higher
|
||||||
- Vérifier que Stream Deck software est fermé pendant l'installation
|
- **Node.js**: Version 20 or higher
|
||||||
- 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
|
|
||||||
|
|||||||
Reference in New Issue
Block a user