webhooks-trigger/README.md

# Webhooks Trigger - Stream Deck Plugin

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.

## 🚀 Features

- **Complete HTTP Support**: GET, POST, PUT, PATCH, DELETE methods
- **Flexible Configuration**: Customizable URL, headers, body, and HTTP method
- **JSON Validation**: Real-time validation of headers and body JSON
- **JSON Beautification**: Automatic JSON formatting with proper indentation
- **Configuration Verification**: Complete validation with error detection
- **Visual Feedback**: Success/failure indication directly on Stream Deck
- **Comprehensive Logging**: Detailed logs for debugging and monitoring
- **Modern UI**: Clean interface with SDPI components

## 📦 Installation

### Prerequisites

- Official Stream Deck software installed
- Node.js 20+ and npm
- Stream Deck CLI (`npm install -g @elgato/cli`)

### Developer Installation

1. **Clone the repository**

    ```bash
    git clone <repository-url>
    cd webhooks-trigger
    ```

2. **Install dependencies**

    ```bash
    npm install
    ```

3. **Build the plugin**

    ```bash
    npm run build
    ```

4. **Install in development mode**

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

5. **Restart the plugin (after modifications)**
    ```bash
    npm run restart
    ```

## ⚙️ Configuration

### Configuration Fields

| Field           | Description                 | Required | Example                                |
| --------------- | --------------------------- | -------- | -------------------------------------- |
| **URL**         | Webhook destination URL     | ✅       | `https://webhook.site/abc123`          |
| **HTTP Method** | HTTP method to use          | ✅       | `POST`                                 |
| **Headers**     | HTTP headers in JSON format | ❌       | `{"Content-Type": "application/json"}` |
| **Body**        | Request body content        | ❌       | `{"message": "Hello!"}`                |

> **Note**: Button title is managed natively by Stream Deck through the standard interface.

### Configuration Examples

#### Simple GET Webhook

```
URL: https://api.example.com/webhook
Method: GET
Headers: {"Authorization": "Bearer token123"}
Body: (empty)
```

#### POST Webhook with JSON

```
URL: https://webhook.site/abc123
Method: POST
Headers: {"Content-Type": "application/json"}
Body: {"event": "button_pressed", "timestamp": "now"}
```

#### Discord Notification

```
URL: https://discord.com/api/webhooks/your-webhook-url
Method: POST
Headers: {"Content-Type": "application/json"}
Body: {"content": "Message from Stream Deck!"}
```

## 🛠️ User Interface

### Validation Buttons

- **Beautify JSON**: Automatically formats JSON with proper indentation
- **Validate JSON**: Checks JSON syntax and displays errors
- **Verify Configuration**: Complete validation of all configuration settings

### Validation Messages

- **Errors**: Displayed in red below fields for 5 seconds
- **Success**: Displayed in green for 5 seconds
- **Real-time Validation**: Automatic verification during input
- **Timeout Management**: Previous timeouts are automatically cleared

### Stream Deck Visual Feedback

- **✅ Green Checkmark**: Request sent successfully (status 200-299)
- **❌ Red X**: Error occurred (invalid URL, malformed JSON, network error)

## 📋 Validation Rules

### URL Validation

- ✅ Supported protocols: `http://` and `https://`
- ✅ Valid URL format required
- ❌ Relative URLs not supported

### Headers Validation

- ✅ Valid JSON object: `{"key": "value"}`
- ❌ Arrays not supported: `["value1", "value2"]`
- ❌ Primitives not supported: `"string"` or `123`

### Body Validation

- ✅ Valid JSON or plain text
- ✅ Empty allowed (optional)
- ⚠️ Warning if body is empty for POST/PUT/PATCH
- ⚠️ Warning if body is present for GET

### Best Practices

- **Content-Type Recommended**: Add `{"Content-Type": "application/json"}` for JSON body requests
- **Authentication Headers**: Use `{"Authorization": "Bearer token"}` for authentication
- **Pre-validation**: Use "Verify Configuration" button before first use

## 🔧 Development

### Project Structure

```
webhooks-trigger/
├── src/                                 # TypeScript source code
│   ├── actions/
│   │   └── send-webhook.ts             # Main plugin action
│   ├── services/                       # Service modules
│   │   ├── validation-service.ts       # Validation logic
│   │   ├── webhook-request-builder.ts  # HTTP request construction
│   │   ├── webhook-executor.ts         # Request execution
│   │   └── settings-manager.ts         # Settings management
│   ├── types/
│   │   └── webhook-settings.ts         # TypeScript types and constants
│   └── plugin.ts                       # Plugin entry point
├── com.mr-kayjaydee.webhooks-trigger.sdPlugin/  # Stream Deck plugin
│   ├── manifest.json                   # Plugin metadata
│   ├── ui/
│   │   ├── send-webhook.html           # User interface
│   │   └── send-webhook.js             # Frontend JavaScript
│   ├── bin/
│   │   ├── plugin.js                   # Compiled code (generated)
│   │   └── package.json                # ES module config (generated)
│   └── imgs/                           # Icons and assets
├── package.json                        # Dependencies and scripts
├── tsconfig.json                       # TypeScript configuration
└── rollup.config.mjs                  # Build configuration
```

### Available Scripts

```bash
npm run build          # Compile TypeScript to JavaScript
npm run watch          # Development mode with watch and auto-restart
npm run restart        # Build + restart plugin
```

### HTTP Methods

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

### Error Handling

The plugin handles various error scenarios:

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

## 🚨 Troubleshooting

### Common Issues

1. **Plugin Not Appearing**
    - Ensure Stream Deck software is running
    - Check if plugin is properly linked with `streamdeck link`
    - Restart Stream Deck software

2. **Webhook Not Sending**
    - Verify URL is accessible
    - Check network connectivity
    - Validate JSON syntax in headers/body
    - Review Stream Deck logs

3. **JSON Validation Errors**
    - Use the "Beautify JSON" button to format
    - Check for missing quotes, commas, or brackets
    - Ensure headers are objects, not arrays

### Debug Logging

The plugin includes comprehensive logging. To view logs:

1. Open Stream Deck software
2. Go to preferences → Advanced → Enable debug logging
3. Check the plugin logs directory

## 📄 License

This project is licensed under the MIT License.

## 👤 Author

**Mr-KayJayDee**

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📊 System Requirements

- **Stream Deck Software**: 6.5 or higher
- **Operating System**:
    - Windows 10 or higher
    - macOS 12 or higher
- **Node.js**: Version 20 or higher