@silentjma/n8n-nodes-unraid 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this package. Versions follow [semver](https://semver.org/).
+
+## Unreleased
+
+## 0.1.1 - 2026-10-26
+
+Passes n8n's community package scanner (`npx @n8n/scan-community-package @silentjma/n8n-nodes-unraid`).
+
+### Fixed
+- `package.json`: `author` now includes the npm owner's email. The scanner requires an author email (`valid-author`), and n8n's Creator Portal reads it from npm to match the package to its owner ("Error getting author email from npm").
+- Nodes declare their inputs and outputs with `NodeConnectionTypes.Main`.
+- Errors from an operation are always raised as `NodeApiError` or `NodeOperationError`, with the item index, so n8n shows them properly per item.
+- An invalid log filter pattern now fails with a clear node error. It no longer throws a plain `Error` from the log helpers.
+
+### Added
+- Credential icon. Node icons use the light/dark form.
+- `npm run lint` now includes n8n's community node rules (`@n8n/eslint-plugin-community-nodes`, the ruleset the scanner runs), so CI catches scan failures before a release. ESLint is pinned to 9.29.0 to match that plugin.
+
+### Docs
+- Telegram needs a public HTTPS webhook. Set `N8N_WEBHOOK_URL`; on n8n 2.x, `WEBHOOK_URL` alone leaves test webhooks on the editor URL.
+
+### Project
+- Community files: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, SUPPORT, issue and pull request templates, Dependabot.
+- CI on every push and pull request. A release workflow publishes to npm with provenance when a `v*` tag is pushed.
+- Buy Me a Coffee funding link.
+
+## 0.1.0 - 2026-10-25
+
+First release.
+
+### Nodes
+- **Unraid** action node:
+  - System: health report with suggested next steps, info, metrics.
+  - Array: status, start, stop, parity check start, pause, resume and cancel, parity history.
+  - Disks and shares.
+  - Docker: list, get, logs (analysed), update status, check for updates, start, stop, restart, pause, unpause, update one or more containers, update all.
+  - VMs: list, start, stop, force stop, pause, resume, reboot, reset.
+  - Log files: list and read, with a regex filter and severity analysis.
+  - Notifications: create (optionally only if unique), list, overview, warnings and alerts, archive.
+  - Custom GraphQL.
+- **Unraid Trigger** polling events: log file lines, container log lines, health problems (optionally resolved ones too), new notifications, container state changes, container updates available.
+- **Unraid API** credential: server URL, `x-api-key`, and an option to accept self-signed certificates. The credential test fails on a revoked or invalid key, even though Unraid answers those with HTTP 200.
+- Containers can be given by name, ID or command-safe name (`plex_media_server`).
+- Built-in rules for log lines and health findings, each with next steps:
+  - Logs: disk I/O, filesystem corruption, OOM, hardware/MCE, kernel traces, disk space, parity, auth failures, segfaults, Docker, network, temperature, application fatal errors.
+  - Health: array state, disk status, errors, temperature (separate HDD and SSD thresholds) and usage, SMART, parity, stopped autostart containers, updates, memory, CPU, Unraid alerts.
+
+### Workflows
+- `unraid-alerts.json`, `unraid-docker.json` and `unraid-sysadmin-bot.json`: alerts, Docker updates and on-demand actions, and sysadmin commands, all managed from a Telegram bot.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mohamed Ayoub Jabane
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# @silentjma/n8n-nodes-unraid
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@silentjma/n8n-nodes-unraid?logo=npm)](https://www.npmjs.com/package/@silentjma/n8n-nodes-unraid)
+[![CI](https://github.com/SilentJMA/n8n-nodes-unraid/actions/workflows/ci.yml/badge.svg)](https://github.com/SilentJMA/n8n-nodes-unraid/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20coffee-support-FFDD00?logo=buymeacoffee&logoColor=black)](https://www.buymeacoffee.com/kilwanitrod)
+
+Unofficial n8n community nodes for the [Unraid API](https://docs.unraid.net/API/) (GraphQL, [unraid/api](https://github.com/unraid/api)).
+
+- **Unraid**: an action node for System, Array, Disk, Share, Docker Container, Virtual Machine, Log File and Notification, plus a Custom GraphQL operation.
+- **Unraid Trigger**: a polling trigger for new log lines (syslog or a container log), health problems, notifications, container state changes and container updates.
+
+Both nodes use the same built-in rules ([src/lib/analysis.ts](src/lib/analysis.ts)). The rules tag log lines and health findings as `info`, `warning` or `critical` and attach **suggested next steps**.
+
+## Installation
+
+📦 **npm:** [@silentjma/n8n-nodes-unraid](https://www.npmjs.com/package/@silentjma/n8n-nodes-unraid)
+
+**Community Nodes (recommended):** in n8n, open **Settings › Community Nodes › Install** and enter `@silentjma/n8n-nodes-unraid`.
+
+**Manual / custom folder:** run `npm pack` and extract the tarball's `package/` folder into `~/.n8n/custom/n8n-nodes-unraid`. In Docker that is `/home/node/.n8n/custom`, which on Unraid is usually `/mnt/user/appdata/n8n/custom`. Then restart n8n.
+
+Prefer workflows without a community node? [n8n-unraid-telegram-workflows](https://github.com/SilentJMA/n8n-unraid-telegram-workflows) has the same three workflows built only from n8n's built-in nodes.
+
+## Requirements
+
+- Unraid 7.2+ has the API built in. Older versions need the Unraid Connect plugin.
+- An API key, created in **Settings › Management Access › API Keys** or with `unraid-api apikey --create`. Read operations work with a read-only role. Updates, restarts and array/VM control need **admin**.
+
+## Credential: Unraid API
+
+| Field | Notes |
+| --- | --- |
+| Server URL | WebGUI base URL, e.g. `https://192.168.1.10`. Requests go to `<url>/graphql` with header `x-api-key`. Use https when SSL is enabled: Unraid redirects http, and the request body is lost. |
+| API Key | The key from the WebGUI |
+| Ignore SSL Issues | For self-signed certificates |
+
+## Unraid node operations
+
+| Resource | Operations |
+| --- | --- |
+| System | Get Health Report (findings + next steps), Get Info, Get Metrics |
+| Array | Get Status, Start, Stop, Start / Pause / Resume / Cancel Parity Check, Get Parity History |
+| Disk / Share | Get Many |
+| Docker Container | Get, Get Many (filters: state, updates only, autostart, name), Get Logs (analysed), Get Update Status, Check for Updates, Start, Stop, Restart, Pause, Unpause, Update (one or many), Update All |
+| Virtual Machine | Get Many, Start, Stop, Force Stop, Pause, Resume, Reboot, Reset |
+| Log File | Get Many (`/var/log`), Read (last N lines or from a line; regex filter; analysis; one item or one per line) |
+| Notification | Create (optionally only if unique), Get Many, Get Overview, Get Warnings and Alerts, Archive, Archive All |
+| Custom GraphQL | Execute any query or mutation |
+
+
+<img width="638" height="763" alt="{0E837C8A-E0E8-4CB5-903F-C4CD4459B37A}" src="https://github.com/user-attachments/assets/a3143eab-9a77-4ef6-99b7-35f639eb996e" />
+
+Containers can be given by **name** (`plex`) or ID.
+
+## Unraid Trigger events
+
+| Event | Fires on |
+| --- | --- |
+| Log File Line | New lines in a `/var/log` file at or above the minimum severity. Tracks the line count and handles log rotation. |
+| Container Log Line | New lines in a container's log (cursor based) |
+| Health Problem | A finding not reported before. Can also emit "resolved" items. |
+| New Notification | New unread Unraid notification at or above an importance |
+| Container State Changed | Start / stop / pause / removal |
+| Container Update Available | A container newly has an image update |
+
+On the first poll, the trigger only records a baseline. Turn on *Emit Existing on First Poll* to also get what already exists. Manual "Fetch Test Event" always returns current data.
+
+## Workflows (managed from Telegram)
+
+`npm run workflow` ([scripts/build-workflows.mjs](scripts/build-workflows.mjs)) generates three workflows in [workflows/](workflows/):
+
+| Workflow | Triggers | What it does |
+| --- | --- | --- |
+| [Unraid · Alerts](workflows/unraid-alerts.json) | Syslog every minute, health report every 5 min | Sends each new problem to Telegram with suggested next steps and tappable follow-up commands (`/logs_sonarr`, `/disks`…). Repeats are throttled (60 min per alert key). Optional: AI triage (disabled by default), an Unraid notification as well, and automatic restart of stopped autostart containers. |
+| [Unraid · Docker updates & actions](workflows/unraid-docker.json) | Weekly (Sun 04:00), and called by the bot | Weekly: updates every container that has a new image, except `cfg.excludeFromUpdates`. It reports only when something changed. Also answers the Docker commands. |
+| [Unraid · Sysadmin & Telegram bot](workflows/unraid-sysadmin-bot.json) | Telegram Trigger | The bot. Answers the sysadmin commands and forwards Docker commands to the Docker workflow. |
+
+<img width="1184" height="743" alt="image" src="https://github.com/user-attachments/assets/606adfce-023e-4d05-b873-b86bea7c8f0e" />
+
+
+A Telegram bot delivers updates to a single webhook, so **only the bot workflow has a Telegram Trigger**. The other two just send messages.
+
+### Commands
+
+| Server | Docker |
+| --- | --- |
+| `/status`: health report with next steps | `/containers`: list with quick actions |
+| `/info`: uptime, CPU, RAM, array usage | `/updates`: check for image updates |
+| `/disks`: status, temperature, usage, errors | `/update_all`: update all (asks first) |
+| `/parity`, `/parity_start` (asks first), `/parity_pause`, `/parity_resume`, `/parity_cancel` | `/update_<name>`, `/restart_<name>`, `/start_<name>` |
+| `/syslog`: recent warnings with next steps | `/stop_<name>` (asks first) |
+| `/notifications`, `/archive_all` | `/logs_<name>`: last lines, analysed |
+| `/vms`, `/help` | |
+
+Telegram commands allow only `a-z0-9_`, so container names are written with underscores: `Plex-Media-Server` becomes `/logs_plex_media_server`. Actions that ask first reply with a `…_confirm` command to tap.
+
+For autocomplete, send this to @BotFather with `/setcommands`:
+
+```text
+status - Health report with next steps
+info - Uptime, CPU, RAM, array usage
+disks - Disk status and temperatures
+containers - Docker containers with quick actions
+updates - Check for container updates
+syslog - Recent syslog warnings
+parity - Parity check status
+notifications - Unread Unraid notifications
+help - All commands
+```
+
+### Setup
+
+1. Create a bot with @BotFather and add a **Telegram** credential in n8n with its token.
+   n8n must be reachable at a **public HTTPS** address (for example a Cloudflare Tunnel or a reverse proxy), and the n8n container needs `N8N_WEBHOOK_URL=https://<that host>/`, otherwise Telegram rejects the trigger with *Bad request*. See [SUPPORT.md](SUPPORT.md).
+2. Import the three workflows. In each one, select the **Unraid API** credential (your server as `https://<unraid-ip>`, Ignore SSL Issues on) and the Telegram credential.
+3. Publish the **Sysadmin & Telegram bot** workflow and send the bot any message. While `cfg.allowedChatIds` is empty, the bot only replies with your chat ID and runs nothing else.
+4. Put that ID in **Bot settings › cfg.allowedChatIds**, **Alert settings › cfg.telegramChatId** and **Settings › cfg.telegramChatId** (Docker workflow). After that, the bot ignores every other chat.
+5. In the bot's **Run Docker workflow** node, pick *Unraid · Docker updates & actions*. Alternatively, regenerate with `DOCKER_WORKFLOW_ID=<id> npm run workflow` and re-import.
+6. Publish the Docker and Alerts workflows.
+
+Keep **n8n** in `cfg.excludeFromUpdates`. Updating it recreates the container that is running the workflow, so the run is cut off and no report arrives.
+
+The workflows use node types `CUSTOM.unraid` / `CUSTOM.unraidTrigger`, which n8n uses for nodes in `~/.n8n/custom`. If you install the package through Community Nodes, generate with `UNRAID_NODE_PREFIX=@silentjma/n8n-nodes-unraid npm run workflow`.
+
+## Development
+
+See [AGENT.md](AGENT.md) for the full maintenance and release procedure.
+
+```bash
+npm install
+npm run build && npm run lint && npm run typecheck && npm test
+npm pack   # -> silentjma-n8n-nodes-unraid-0.1.0.tgz
+```
+
+The queries in [src/lib/queries.ts](src/lib/queries.ts) are written against `api/generated-schema.graphql` from the unraid/api repository. Check them again when Unraid changes the schema.
+
+## Support and contributing
+
+- **Questions:** [Discussions › Q&A](https://github.com/SilentJMA/n8n-nodes-unraid/discussions/categories/q-a). Common problems are listed in [SUPPORT.md](SUPPORT.md).
+- **Bugs and feature requests:** [open an issue](https://github.com/SilentJMA/n8n-nodes-unraid/issues/new/choose) using the templates. Never paste API keys or tokens.
+- **Security:** report privately, see [SECURITY.md](SECURITY.md).
+- **Contributing:** pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) and the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+If these nodes save you time, you can support the project:
+
+<a href="https://www.buymeacoffee.com/kilwanitrod"><img src="https://img.buymeacoffee.com/button-api/?text=Buy%20me%20a%20coffee&emoji=%E2%98%95&slug=kilwanitrod&button_colour=FFDD00&font_colour=000000&font_family=Inter&outline_colour=000000&coffee_colour=ffffff" alt="Buy me a coffee" height="40"></a>
+
+## License
+
+[MIT](LICENSE). Not affiliated with or endorsed by Lime Technology / Unraid.

package/dist/credentials/UnraidApi.credentials.js

@@ -0,0 +1,68 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnraidApi = void 0;
+class UnraidApi {
+    name = 'unraidApi';
+    displayName = 'Unraid API';
+    icon = { light: 'file:../nodes/Unraid/unraid.svg', dark: 'file:../nodes/Unraid/unraid.svg' };
+    documentationUrl = 'https://docs.unraid.net/API/how-to-use-the-api/';
+    properties = [
+        {
+            displayName: 'Server URL',
+            name: 'serverUrl',
+            type: 'string',
+            default: 'https://tower.local',
+            placeholder: 'https://192.168.1.10',
+            required: true,
+            description: 'Base URL of the Unraid WebGUI; requests go to /graphql. Use https:// when SSL is enabled (Unraid redirects http:// and the request would fail).',
+        },
+        {
+            displayName: 'API Key',
+            name: 'apiKey',
+            type: 'string',
+            typeOptions: { password: true },
+            default: '',
+            required: true,
+            description: 'Created in Settings › Management Access › API Keys (or "unraid-api apikey --create"). Docker updates, array and VM control need the admin role.',
+        },
+        // A boolean switch, not a secret: the rule matches "cert" in the name. Renaming it would reset saved credentials.
+        // eslint-disable-next-line @n8n/community-nodes/credential-password-field
+        {
+            displayName: 'Ignore SSL Issues',
+            name: 'allowUnauthorizedCerts',
+            type: 'boolean',
+            default: false,
+            description: 'Whether to connect even if the server uses a self-signed or otherwise invalid certificate (the default for Unraid on a LAN IP)',
+        },
+    ];
+    authenticate = {
+        type: 'generic',
+        properties: {
+            headers: {
+                'x-api-key': '={{$credentials.apiKey}}',
+            },
+        },
+    };
+    test = {
+        request: {
+            baseURL: '={{$credentials.serverUrl.replace(/\\/+$/, "")}}',
+            url: '/graphql',
+            method: 'POST',
+            skipSslCertificateValidation: '={{$credentials.allowUnauthorizedCerts}}',
+            headers: { 'Content-Type': 'application/json' },
+            body: { query: '{ online info { os { hostname } } }' },
+        },
+        // Unraid answers HTTP 200 with a GraphQL error for a bad key, so check the body.
+        rules: [
+            {
+                type: 'responseSuccessBody',
+                properties: { key: 'errors[0].extensions.code', value: 'UNAUTHENTICATED', message: 'Invalid or revoked API key' },
+            },
+            {
+                type: 'responseSuccessBody',
+                properties: { key: 'errors[0].extensions.code', value: 'FORBIDDEN', message: 'The API key may not read server info; give it at least a read role' },
+            },
+        ],
+    };
+}
+exports.UnraidApi = UnraidApi;