feat: pluggable multi-channel notification hub (Telegram, Bale, Pushover, Gotify, ntfy)

- MCP server with send_message, send_alert, send_log, send_file, list_channels
- REST API with per-channel selection and per-call delivery report
- Telegram bot UI with /channels and /status
- Severity -> native priority mapping per channel
- Non-root Docker image with healthcheck
- CI matrix on Node 20 & 22 + docker build
- Smoke test suite (no network required)

Author: MMTE

.dockerignore

@@ -0,0 +1,12 @@
+node_modules
+uploads
+.env
+.env.*
+.git
+.gitignore
+.github
+*.md
+!README.md
+Dockerfile
+docker-compose.yml
+test

.env.example

@@ -0,0 +1,38 @@
+# --- Core ---
+API_PORT=3000
+API_KEY=watchtower_secret_key_change_me
+
+# Optional: comma-separated default fan-out list. If unset, all enabled
+# channels are used unless the API/MCP request specifies "channels".
+# Example: DEFAULT_CHANNELS=telegram,ntfy
+DEFAULT_CHANNELS=
+
+# --- Telegram channel ---
+TELEGRAM_BOT_TOKEN=
+TELEGRAM_CHAT_ID=
+# If set, Telegram uses webhook mode; otherwise polling.
+WEBHOOK_URL=
+
+# --- Bale channel (Telegram-compatible BotAPI) ---
+BALE_BOT_TOKEN=
+BALE_CHAT_ID=
+
+# --- Pushover channel ---
+# https://pushover.net
+PUSHOVER_APP_TOKEN=
+PUSHOVER_USER_KEY=
+PUSHOVER_DEVICE=
+
+# --- Gotify channel ---
+# https://gotify.net
+GOTIFY_URL=
+GOTIFY_APP_TOKEN=
+
+# --- ntfy channel ---
+# Public: https://ntfy.sh ; or self-hosted URL
+NTFY_URL=https://ntfy.sh
+NTFY_TOPIC=
+# Optional auth:
+NTFY_TOKEN=
+NTFY_USER=
+NTFY_PASSWORD=

.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      - run: npm ci
+
+      - name: Syntax check
+        run: |
+          for f in src/*.js src/channels/*.js test/*.js; do
+            node --check "$f"
+          done
+
+      - name: Smoke test
+        run: npm test
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: test
+    steps:
+      - uses: actions/checkout@v4
+      - name: Build image
+        run: docker build -t watch-tower:ci .

.gitignore

@@ -0,0 +1,23 @@
+# dependencies
+node_modules/
+
+# secrets
+.env
+.env.*
+!.env.example
+
+# uploads (runtime)
+uploads/*
+!uploads/.gitkeep
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+*.log
+
+# editor / OS
+.vscode/
+.idea/
+.DS_Store
+Thumbs.db

CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog
+
+All notable changes to this project will be documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning follows [SemVer](https://semver.org/).
+
+## [1.1.0] - 2026-05-28
+
+### Added
+- Pluggable channel architecture under `src/channels/`.
+- Pushover, Gotify, and ntfy channels.
+- Per-request `channels` selector on every REST endpoint and MCP tool.
+- `DEFAULT_CHANNELS` env to scope the default fan-out list.
+- New MCP tools: `send_file`, `list_channels`.
+- `/api/channels` REST endpoint and `/channels` Telegram bot command.
+- Severity → priority mapping for Pushover (-1..2), Gotify (2..10), ntfy (1..5 + tags).
+- Per-channel delivery report in API responses (`delivered`, `errors`).
+- Automatic cleanup of files in `uploads/` after `/api/file` dispatch.
+- Smoke test (`npm test`) covering channel resolution and dispatcher.
+- LICENSE (MIT), CONTRIBUTING, SECURITY, CHANGELOG, GitHub Actions CI.
+
+### Changed
+- API response shape now reports per-channel outcome and returns `502` when no channel delivered.
+- Telegram bot UI moved out of the channel module into `src/bot.js`.
+- Dockerfile runs as a non-root user with a healthcheck.
+- `docker-compose.yml` is now generic (no personal network or hostname).
+
+### Removed
+- Hard-coded production URL from the README.
+- Old `src/bale.js` (replaced by `src/channels/bale.js`).
+
+## [1.0.0]
+
+- Initial release: Telegram bot + REST API + MCP server.

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to Watch Tower
+
+Thanks for your interest! Watch Tower is intentionally small and pluggable.
+
+## Dev setup
+
+```bash
+git clone https://github.com/MMTE/watch-tower.git
+cd watch-tower
+npm install
+cp .env.example .env       # fill only the channels you want to test
+npm start                  # REST API + Telegram bot
+npm run mcp                # MCP server over stdio
+npm test                   # smoke test (no network required)
+```
+
+Node ≥ 20 is required (uses global `fetch` / `FormData`).
+
+## Adding a new channel
+
+A channel is a CommonJS module under [`src/channels/`](src/channels) that exports:
+
+```js
+module.exports = {
+  name: 'mychannel',           // lowercase, unique
+  enabled: Boolean(/* env */), // computed at load time
+  async sendMessage(text, { title, level, parse_mode } = {}) { /* ... */ },
+  async sendFile(filePath, { caption, filename, title, level } = {}) { /* ... */ },
+};
+```
+
+Then register it in the `ALL` array in [`src/channels/index.js`](src/channels/index.js) and add its env vars to [`.env.example`](.env.example) and the channel table in [`README.md`](README.md).
+
+Guidelines:
+
+- Map the four severity levels (`info`, `warn`, `error`, `critical`) to your channel's native priority if it has one.
+- If your channel can't natively attach files, fall back to a textual message (see [`gotify.js`](src/channels/gotify.js)).
+- Throw on hard failures so the dispatcher can report them per-channel; don't swallow errors silently.
+
+## Style
+
+- Plain CommonJS, no build step.
+- Match the surrounding style; no linter is configured.
+- Keep changes small and focused. New runtime dependencies need a clear reason.
+
+## Pull requests
+
+1. Fork and branch from `main`.
+2. Run `npm test` before pushing.
+3. Update [`README.md`](README.md) and [`CHANGELOG.md`](CHANGELOG.md) when behavior changes.
+4. Describe what you changed and why in the PR body.
+
+## Reporting bugs
+
+Open an issue with reproduction steps, the channels involved, Node version, and any redacted error output. Please redact tokens and chat IDs.

Dockerfile

@@ -0,0 +1,21 @@
+FROM node:20-alpine
+
+WORKDIR /app
+
+# Install production dependencies first for better layer caching
+COPY package.json package-lock.json* ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+# Copy source
+COPY src ./src
+
+# Run as non-root, ensure uploads dir is owned correctly
+RUN mkdir -p uploads && chown -R node:node /app
+USER node
+
+EXPOSE 3000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+  CMD wget -qO- http://127.0.0.1:3000/api/health || exit 1
+
+CMD ["node", "src/index.js"]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Watch Tower contributors
+
+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.