thormail-adapter-generic-rest 1.0.1

package/README.md

@@ -0,0 +1,80 @@
+# ThorMail Generic REST API Adapter
+
+A highly configurable adapter for [ThorMail](https://thormail.io) that allows sending messages to any generic REST API.
+
+## 📖 Overview
+
+This adapter provides a flexible bridge between ThorMail and any external service that accepts HTTP requests (POST, PUT, PATCH, GET). It is ideal for:
+
+- Integrating with bespoke internal APIs.
+- Connecting to small providers without dedicated adapters.
+- Prototyping new integrations quickly.
+- Webhook-based messaging.
+
+## 🛠️ Configuration
+
+When creating a new Connection in ThorMail, select **Generic REST API** and configure the following fields:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| **Base URL** | `text` | The full HTTP(S) endpoint of the external API. |
+| **HTTP Method**| `select` | The method to use (POST, PUT, PATCH, GET). |
+| **Custom Headers** | `customHeaders` | Headers required for authentication or metadata (e.g., `Authorization`). |
+| **Payload Template** | `json-template` | A JSON template with `{{to}}`, `{{subject}}`, and `{{body}}` placeholders. |
+| **Success Status Code(s)** | `text` | Comma-separated list of successful HTTP codes (default: `200,201,202`). |
+
+### Payload Replacements
+
+You can use the following variables in your **Payload Template**:
+
+- `{{to}}`: The recipient's identifier (address, phone, ID).
+- `{{subject}}`: The message subject or title.
+- `{{body}}`: The main content of the message.
+- `{{any_data_key}}`: Any key passed in the `data` object during the send request.
+
+### Example Configuration: Simple Webhook
+
+- **Base URL**: `https://hooks.example.com/services/T0000/B0000/XXXX`
+- **Method**: `POST`
+- **Payload Template**:
+
+```json
+{
+  "text": "New Mail to {{to}}: {{subject}}",
+  "details": "{{body}}"
+}
+```
+
+### Example Configuration: authenticated API
+
+- **Base URL**: `https://api.provider.com/v1/messages`
+- **Method**: `POST`
+- **Custom Headers**:
+  - `X-API-Key`: `your-secret-key`
+  - `Content-Type`: `application/json`
+- **Payload Template**:
+
+```json
+{
+  "recipient": "{{to}}",
+  "title": "{{subject}}",
+  "html_body": "{{body}}",
+  "metadata": {
+    "source": "thormail"
+  }
+}
+```
+
+## 🚀 Features
+
+- **Standard Idempotency**: Automatically sends `Idempotency-Key` or `X-Idempotency-Key` headers if available.
+- **Smart Retries**: Correctly identifies 429 and 5xx errors as temporary for ThorMail's retry logic.
+- **Custom Success Logic**: Configurable success status codes to match legacy or non-standard APIs.
+- **Dynamic Headers**: Merges headers provided in the specific send request with the global configuration.
+
+## 📜 License
+
+This adapter is licensed under the MIT License. See the main ThorMail repository for details.
+
+---
+*Powered by [ThorMail](https://thormail.io) - The God of Deliveries.*

package/index.js

@@ -0,0 +1,330 @@
+/**
+ * Generic REST API Adapter for ThorMail
+ * Allows sending messages via any RESTful API with configurable endpoints and payloads.
+ */
+export default class GenericRestAdapter {
+    /**
+     * Defines the configuration form schema for the frontend.
+     */
+    static getConfigSchema() {
+        return [
+            {
+                name: 'custom_name',
+                label: 'Name',
+                type: 'text',
+                required: false,
+                placeholder: 'My Generic API',
+                hint: 'Internal name for this adapter instance.',
+                group: 'settings'
+            },
+            {
+                name: 'baseUrl',
+                label: 'Base URL',
+                type: 'text',
+                required: true,
+                placeholder: 'https://api.myservice.com/v1/send',
+                hint: 'The full URL endpoint where the request will be sent.',
+                group: 'connection'
+            },
+            {
+                name: 'method',
+                label: 'HTTP Method',
+                type: 'select',
+                required: true,
+                options: ['POST', 'PUT', 'PATCH', 'GET'],
+                placeholder: 'POST',
+                hint: 'The HTTP method to use for sending the message.',
+                group: 'connection'
+            },
+            {
+                name: 'customHeaders',
+                label: 'Custom Headers',
+                type: 'customHeaders',
+                required: false,
+                hint: 'Optional HTTP headers to include in the request (e.g., Authorization, X-API-Key).',
+                group: 'authentication'
+            },
+            {
+                name: 'payloadTemplate',
+                label: 'Payload Template',
+                type: 'json-template',
+                required: false,
+                placeholder: '{\n  "recipient": "{{to}}",\n  "content": "{{body}}"\n}',
+                hint: 'A JSON template for the request body. Values like {{to}}, {{subject}}, and {{body}} will be automatically replaced.',
+                group: 'payload'
+            },
+            {
+                name: 'successStatus',
+                label: 'Success Status Code(s)',
+                type: 'text',
+                required: false,
+                placeholder: '200,201,202',
+                hint: 'Comma-separated list of HTTP status codes to treat as success. Defaults to 200, 201, 202.',
+                group: 'validation'
+            },
+            {
+                name: 'from_email',
+                label: 'From Email',
+                type: 'text',
+                required: false,
+                placeholder: 'noreply@yourdomain.com',
+                hint: 'Default sender email address if required by the destination API.',
+                group: 'defaults'
+            },
+            {
+                name: 'from_name',
+                label: 'From Name',
+                type: 'text',
+                required: false,
+                placeholder: 'My App',
+                hint: 'Default sender name.',
+                group: 'defaults'
+            }
+        ];
+    }
+
+    /**
+     * Defines adapter metadata for the registry.
+     */
+    static getMetadata() {
+        return {
+            name: 'Generic REST API',
+            description: 'Send messages via any generic REST API with custom payloads and headers.',
+            group: 'generic'
+        };
+    }
+
+    /**
+     * @param {Object} config - The configuration object.
+     */
+    constructor(config) {
+        this.config = config;
+        this.successCodes = (config.successStatus || '200,201,202')
+            .split(',')
+            .map(code => parseInt(code.trim(), 10));
+    }
+
+    /**
+     * Internal helper to make HTTP requests.
+     */
+    async _request(method, url, body = null, headers = {}) {
+        const fetchHeaders = { ...headers };
+
+        // Default Content-Type if body is provided and not already set
+        if (body && !Object.keys(fetchHeaders).some(h => h.toLowerCase() === 'content-type')) {
+            fetchHeaders['Content-Type'] = 'application/json';
+        }
+
+        const fetchOptions = {
+            method,
+            headers: fetchHeaders
+        };
+
+        if (body && method !== 'GET' && method !== 'HEAD') {
+            fetchOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+        }
+
+        try {
+            const response = await fetch(url, fetchOptions);
+            const status = response.status;
+            let responseData;
+            const text = await response.text();
+
+            try {
+                responseData = text ? JSON.parse(text) : {};
+            } catch (e) {
+                responseData = { raw: text };
+            }
+
+            const success = this.successCodes.includes(status);
+
+            if (!success) {
+                // Determine if temporary error
+                // 429 (Rate Limit) and 5xx (Server Error) are usually temporary
+                const isTemporary = status === 429 || (status >= 500 && status < 600);
+
+                return {
+                    success: false,
+                    error: `HTTP ${status}: ${text.substring(0, 500)}`,
+                    isTemporary,
+                    status,
+                    response: responseData
+                };
+            }
+
+            return { success: true, data: responseData, status };
+        } catch (error) {
+            return {
+                success: false,
+                error: `Network/Fetch Error: ${error.message}`,
+                isTemporary: true
+            };
+        }
+    }
+
+    /**
+     * Validates configuration by attempting a request to the base URL.
+     */
+    async validateConfig() {
+        try {
+            // For validation, we use the method configured, but if it's POST/PUT/PATCH we don't send a body.
+            // Some APIs might reject this, so we try a simple request.
+            const validationHeaders = this._parseHeaders(this.config.customHeaders);
+
+            // If the user provided a success status, we check if the base URL responds with one of them.
+            // Note: This is an optimistic check.
+            const result = await this._request(this.config.method || 'GET', this.config.baseUrl, null, validationHeaders);
+
+            if (result.success) {
+                return {
+                    success: true,
+                    message: `Successfully reached the endpoint (Status ${result.status}).`,
+                    canValidate: true
+                };
+            } else {
+                return {
+                    success: false,
+                    message: `Endpoint returned error: ${result.error}`,
+                    canValidate: true
+                };
+            }
+        } catch (error) {
+            return {
+                success: false,
+                message: `Validation failed: ${error.message}`,
+                canValidate: true
+            };
+        }
+    }
+
+    /**
+     * Checks if the external service is reachable.
+     */
+    async healthCheck() {
+        const result = await this.validateConfig();
+        return result.success ? 'HEALTHY' : 'UNHEALTHY';
+    }
+
+    /**
+     * Dispatches a message via the configured REST API.
+     * @param {Object} params - { to, subject, body, data, idempotencyKey }
+     */
+    async sendMail({ to, subject, body, data, idempotencyKey }) {
+        try {
+            const method = this.config.method || 'POST';
+            const url = this.config.baseUrl;
+            const headers = this._parseHeaders(this.config.customHeaders);
+
+            // Merge headers from the send request if any
+            if (data && data.headers) {
+                Object.assign(headers, data.headers);
+            }
+
+            // Handle Idempotency Key
+            if (idempotencyKey) {
+                // Common headers for idempotency, can be overridden by customHeaders
+                const idHeaders = ['Idempotency-Key', 'X-Idempotency-Key', 'X-Request-Id'];
+                for (const h of idHeaders) {
+                    if (!Object.keys(headers).some(key => key.toLowerCase() === h.toLowerCase())) {
+                        headers[h] = idempotencyKey;
+                    }
+                }
+            }
+
+            let payload;
+
+            if (this.config.payloadTemplate) {
+                // If a template is provided, we replace variables.
+                // ThorMail core usually provides data with replacements, 
+                // but we also have to, subject, body specifically.
+                let templateStr = this.config.payloadTemplate;
+                const replacements = {
+                    ...data,
+                    to,
+                    subject,
+                    body,
+                    from_email: this.config.from_email || (data && data.from_email),
+                    from_name: this.config.from_name || (data && data.from_name)
+                };
+
+                // Simple mustache-like replacement: {{variable}}
+                payload = templateStr.replace(/\{\{([^}]+)\}\}/g, (match, p1) => {
+                    const key = p1.trim();
+                    return replacements[key] !== undefined ? replacements[key] : match;
+                });
+
+                // Attempt to parse as JSON if it looks like one
+                try {
+                    payload = JSON.parse(payload);
+                } catch (e) {
+                    // Keep as string if not valid JSON
+                }
+            } else {
+                // Default payload if no template is provided
+                payload = {
+                    to,
+                    subject,
+                    content: body,
+                    data
+                };
+            }
+
+            const result = await this._request(method, url, payload, headers);
+
+            if (!result.success) {
+                return result;
+            }
+
+            // Extract ID if possible from response
+            const responseId = result.data?.id || result.data?.messageId || result.data?.result?.id || `rest-${Date.now()}`;
+
+            return {
+                success: true,
+                id: String(responseId),
+                response: result.data,
+                isTemporary: false
+            };
+        } catch (error) {
+            return {
+                success: false,
+                error: `Unexpected Error: ${error.message}`,
+                isTemporary: true
+            };
+        }
+    }
+
+    /**
+     * Processes incoming webhooks (optional for generic REST, as it depends on the destination service).
+     */
+    async webhook(event, headers) {
+        // Generic adapter cannot know the format of webhooks from unknown services.
+        // User should use a specialized adapter or the core's generic webhook handling if available.
+        return null;
+    }
+
+    /**
+     * Helper to parse customHeaders field.
+     * ThorMail customHeaders type usually comes as an array of objects { key, value } or a JSON object.
+     */
+    _parseHeaders(headersConfig) {
+        const headers = {};
+        if (!headersConfig) return headers;
+
+        if (Array.isArray(headersConfig)) {
+            headersConfig.forEach(h => {
+                if (h.key && h.value) {
+                    headers[h.key] = h.value;
+                }
+            });
+        } else if (typeof headersConfig === 'object') {
+            Object.assign(headers, headersConfig);
+        } else if (typeof headersConfig === 'string') {
+            try {
+                Object.assign(headers, JSON.parse(headersConfig));
+            } catch (e) {
+                // Ignore invalid JSON
+            }
+        }
+        return headers;
+    }
+}

package/package.json

@@ -0,0 +1,19 @@
+{
+    "name": "thormail-adapter-generic-rest",
+    "version": "1.0.1",
+    "description": "Standard REST API adapter for ThorMail. Send messages via any RESTful service with configurable URL, method, and headers.",
+    "main": "index.js",
+    "type": "module",
+    "keywords": [
+        "thormail",
+        "thormail-adapter",
+        "rest",
+        "api",
+        "generic"
+    ],
+    "author": "ThorMail Team",
+    "license": "MIT",
+    "publishConfig": {
+        "registry": "http://lab.lan:4873/"
+    }
+}