Implement Telegram notification provider

Author: zigazajc007

.gitignore

@@ -21,6 +21,7 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 .env.test.local
 .env.production.local
 .env.local
+config.toml
 
 # caches
 .eslintcache

README.md

@@ -4,12 +4,12 @@ A high-performance uptime monitoring system built with Bun and ClickHouse. Recei
 
 ## Features
 
-- **Pulse-Based Monitoring** — Services send heartbeats; missing pulses trigger alerts
-- **Hierarchical Groups** — Organize monitors with flexible health strategies (any-up, all-up, percentage)
-- **Custom Metrics** — Track up to 3 numeric values per monitor (player count, connections, etc.)
-- **Multi-Channel Notifications** — Discord, Email, and Ntfy support with per-monitor control
-- **Real-Time Status Pages** — WebSocket-powered live updates
-- **Self-Healing** — Automatic backfill when the monitor itself recovers from downtime
+- **Pulse-Based Monitoring** - Services send heartbeats; missing pulses trigger alerts
+- **Hierarchical Groups** - Organize monitors with flexible health strategies (any-up, all-up, percentage)
+- **Custom Metrics** - Track up to 3 numeric values per monitor (player count, connections, etc.)
+- **Multi-Channel Notifications** - Discord, Email, Ntfy and Telegram support with per-monitor control
+- **Real-Time Status Pages** - WebSocket-powered live updates
+- **Self-Healing** - Automatic backfill when the monitor itself recovers from downtime
 
 ## Quick Start
 
@@ -82,7 +82,7 @@ curl http://localhost:3000/v1/status/:slug
 | [Pulses](docs/pulses.md)                                               | How pulses work, timing, and best practices |
 | [Configuration Guide](docs/configuration.md)                           | Complete config.toml reference              |
 | [API Reference](docs/api.md)                                           | All endpoints and WebSocket events          |
-| [Notifications](docs/notifications.md)                                 | Setting up Discord, Email, Ntfy             |
+| [Notifications](docs/notifications.md)                                 | Setting up Discord, Email, Ntfy, Telegram   |
 | [Groups & Strategies](docs/groups.md)                                  | Organizing monitors hierarchically          |
 | [Custom Metrics](docs/custom-metrics.md)                               | Tracking additional data points             |
 | [PulseMonitor Integration](docs/pulsemonitor.md)                       | Automated monitoring from multiple regions  |

config.toml config.example.tomlconfig.toml renamed to config.example.toml

@@ -276,4 +276,14 @@ topic = "uptime-monitor"
 #token = "tk_your_token_here"
 # Optional: Username/password authentication
 #username = "your_username"
-#password = "your_password"
+#password = "your_password"
+
+# Telegram configuration for critical alerts
+[notifications.channels.critical.telegram]
+enabled = false
+botToken = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
+chatId = "-1001234567890"
+# Optional: send to a specific forum topic
+# topicId = 123
+# Optional: send silently
+# disableNotification = false

docs/configuration.md

@@ -138,13 +138,13 @@ pulseMonitors = ["US-WEST-1"]
 
 | Field                  | Required | Default | Description                                                  |
 | ---------------------- | -------- | ------- | ------------------------------------------------------------ |
-| `id`                   | Yes      | —       | Unique identifier                                            |
-| `name`                 | Yes      | —       | Display name                                                 |
-| `token`                | Yes      | —       | Secret token for pulse authentication                        |
-| `interval`             | Yes      | —       | Expected pulse interval in seconds (see [Pulses](pulses.md)) |
-| `maxRetries`           | Yes      | —       | Missed pulses before marking down (see [Pulses](pulses.md))  |
-| `resendNotification`   | Yes      | —       | Resend notification every N down checks (0 = never)          |
-| `groupId`              | No       | —       | Parent group ID                                              |
+| `id`                   | Yes      | -       | Unique identifier                                            |
+| `name`                 | Yes      | -       | Display name                                                 |
+| `token`                | Yes      | -       | Secret token for pulse authentication                        |
+| `interval`             | Yes      | -       | Expected pulse interval in seconds (see [Pulses](pulses.md)) |
+| `maxRetries`           | Yes      | -       | Missed pulses before marking down (see [Pulses](pulses.md))  |
+| `resendNotification`   | Yes      | -       | Resend notification every N down checks (0 = never)          |
+| `groupId`              | No       | -       | Parent group ID                                              |
 | `notificationChannels` | No       | `[]`    | Array of notification channel IDs                            |
 | `pulseMonitors`        | No       | `[]`    | Array of PulseMonitor IDs for automated checking             |
 
@@ -217,21 +217,21 @@ notificationChannels = ["critical"]
 
 | Field                  | Required | Default | Description                                      |
 | ---------------------- | -------- | ------- | ------------------------------------------------ |
-| `id`                   | Yes      | —       | Unique identifier                                |
-| `name`                 | Yes      | —       | Display name                                     |
-| `strategy`             | Yes      | —       | `"any-up"`, `"all-up"`, or `"percentage"`        |
-| `degradedThreshold`    | Yes      | —       | Percentage threshold (0-100) for degraded status |
-| `interval`             | Yes      | —       | Used for uptime calculations                     |
+| `id`                   | Yes      | -       | Unique identifier                                |
+| `name`                 | Yes      | -       | Display name                                     |
+| `strategy`             | Yes      | -       | `"any-up"`, `"all-up"`, or `"percentage"`        |
+| `degradedThreshold`    | Yes      | -       | Percentage threshold (0-100) for degraded status |
+| `interval`             | Yes      | -       | Used for uptime calculations                     |
 | `resendNotification`   | No       | `0`     | Resend notification every N down checks          |
-| `parentId`             | No       | —       | Parent group ID for nesting                      |
+| `parentId`             | No       | -       | Parent group ID for nesting                      |
 | `notificationChannels` | No       | `[]`    | Array of notification channel IDs                |
 
 ### Strategy Reference
 
 | Strategy     | UP              | DEGRADED       | DOWN              |
 | ------------ | --------------- | -------------- | ----------------- |
-| `any-up`     | ≥1 child up     | —              | All children down |
-| `all-up`     | All children up | —              | Any child down    |
+| `any-up`     | ≥1 child up     | -              | All children down |
+| `all-up`     | All children up | -              | Any child down    |
 | `percentage` | 100% up         | ≥threshold% up | <threshold% up    |
 
 ## Status Pages
@@ -329,7 +329,7 @@ The reload token is shown in logs at startup if not explicitly configured.
 
 The configuration is validated at startup. Common errors:
 
-- **Duplicate IDs/tokens** — All IDs and tokens must be unique
-- **Invalid references** — Group/notification channel IDs must exist
-- **Circular references** — Groups cannot reference themselves as parents
-- **Missing required fields** — All required fields must be present
+- **Duplicate IDs/tokens** - All IDs and tokens must be unique
+- **Invalid references** - Group/notification channel IDs must exist
+- **Circular references** - Groups cannot reference themselves as parents
+- **Missing required fields** - All required fields must be present

docs/groups.md

@@ -167,7 +167,7 @@ Group uptime is computed from child uptimes using the same strategy:
 
 ## Group History
 
-Groups don't store their own pulses—history is computed from children in real-time.
+Groups don't store their own pulses-history is computed from children in real-time.
 
 ```bash
 # Get raw history (~24h)

docs/notifications.md

@@ -4,9 +4,9 @@ Uptime Monitor supports multiple notification providers. Notifications are organ
 
 ## How It Works
 
-1. **Define channels** — Each channel has a unique ID and can have multiple providers (Discord, Email, Ntfy)
-2. **Assign channels to monitors/groups** — Use the `notificationChannels` array
-3. **Receive alerts** — When a monitor goes down, recovers, or stays down, notifications are sent to all providers in the assigned channels
+1. **Define channels** - Each channel has a unique ID and can have multiple providers (Discord, Email, Ntfy)
+2. **Assign channels to monitors/groups** - Use the `notificationChannels` array
+3. **Receive alerts** - When a monitor goes down, recovers, or stays down, notifications are sent to all providers in the assigned channels
 
 ## Notification Types
 
@@ -175,6 +175,55 @@ password = "secret"
 ntfy subscribe my-uptime-alerts
 ```
 
+## Telegram
+
+Send notifications to Telegram chats, groups, or channels via a bot.
+
+### Configuration
+
+```toml
+[notifications.channels.critical.telegram]
+enabled = true
+botToken = "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
+chatId = "-1001234567890"
+# Optional: send to a specific forum topic
+# topicId = 123
+# Optional: send silently
+# disableNotification = false
+
+```
+
+| Field                 | Required | Description                                     |
+| --------------------- | -------- | ----------------------------------------------- |
+| `enabled`             | Yes      | Enable Telegram notifications                   |
+| `botToken`            | Yes      | Bot API token from @BotFather                   |
+| `chatId`              | Yes      | Target chat/group/channel ID                    |
+| `topicId`             | No       | Forum topic ID (for groups with topics enabled) |
+| `disableNotification` | No       | Send silently without notification sound        |
+
+### Setting Up a Telegram Bot
+
+1. Message [@BotFather](https://t.me/BotFather) on Telegram
+2. Send `/newbot` and follow the prompts
+3. Copy the bot token provided
+4. Add the bot to your group/channel
+5. Get the chat ID:
+   - For groups: add [@userinfobot](https://t.me/userinfobot) to the group, or use the Telegram Bot API `getUpdates` endpoint
+   - For channels: forward a message from the channel to @userinfobot
+   - For direct messages: message the bot and check `getUpdates`
+
+### Forum Topics
+
+If your group has topics (forum mode) enabled, you can send to a specific topic:
+
+```toml
+[notifications.channels.critical.telegram]
+enabled = true
+botToken = "123456:ABC-DEF..."
+chatId = "-1001234567890"
+topicId = 42
+```
+
 ## Assigning Channels to Monitors
 
 ```toml

docs/pulses.md

@@ -30,8 +30,8 @@ interval = 30
 maxRetries = 0    # Mark down immediately on first missed pulse
 ```
 
-- `maxRetries = 0` — Down on the first missed pulse
-- `maxRetries = 3` — Tolerates 3 missed pulses before marking down (roughly `3 x interval from missingPulseDetector` seconds)
+- `maxRetries = 0` - Down on the first missed pulse
+- `maxRetries = 3` - Tolerates 3 missed pulses before marking down (roughly `3 x interval from missingPulseDetector` seconds)
 
 ## Sending Pulses
 
@@ -40,7 +40,7 @@ Pulses are sent via HTTP GET or WebSocket.
 ### HTTP
 
 ```bash
-# Simple pulse — records with current timestamp
+# Simple pulse - records with current timestamp
 curl http://localhost:3000/v1/push/:token
 ```
 

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "uptimemonitor-server",
 	"module": "src/index.ts",
-	"version": "0.2.16",
+	"version": "0.2.17",
 	"type": "module",
 	"private": true,
 	"scripts": {

src/config.ts

@@ -17,7 +17,6 @@ import type {
 import type { NodeClickHouseClientConfigOptions } from "@clickhouse/client/dist/config";
 import { Logger } from "./logger";
 import { type IpExtractionPreset } from "@rabbit-company/web-middleware/ip-extract";
-import { password } from "bun";
 
 export const defaultReloadToken = generateSecureToken();
 
@@ -1074,6 +1073,50 @@ function validateNtfyConfig(config: unknown, channelId: string): any {
 	return result;
 }
 
+function validateTelegramConfig(config: unknown, channelId: string): any {
+	const errors: string[] = [];
+	const cfg = config as Record<string, unknown>;
+
+	if (!isBoolean(cfg.enabled)) {
+		errors.push(`notifications.channels.${channelId}.telegram.enabled must be a boolean`);
+	}
+
+	if (!cfg.enabled) {
+		return { enabled: false };
+	}
+
+	if (!isString(cfg.botToken) || cfg.botToken.trim().length === 0) {
+		errors.push(`notifications.channels.${channelId}.telegram.botToken must be a non-empty string`);
+	}
+
+	if (!isString(cfg.chatId) || cfg.chatId.trim().length === 0) {
+		errors.push(`notifications.channels.${channelId}.telegram.chatId must be a non-empty string`);
+	}
+
+	if (cfg.topicId !== undefined && !isNumber(cfg.topicId)) {
+		errors.push(`notifications.channels.${channelId}.telegram.topicId must be a number if provided`);
+	}
+
+	if (cfg.disableNotification !== undefined && !isBoolean(cfg.disableNotification)) {
+		errors.push(`notifications.channels.${channelId}.telegram.disableNotification must be a boolean if provided`);
+	}
+
+	if (errors.length > 0) {
+		throw new ConfigValidationError(errors);
+	}
+
+	const result: any = {
+		enabled: cfg.enabled,
+		botToken: cfg.botToken,
+		chatId: cfg.chatId,
+	};
+
+	if (cfg.topicId !== undefined) result.topicId = cfg.topicId;
+	if (cfg.disableNotification !== undefined) result.disableNotification = cfg.disableNotification;
+
+	return result;
+}
+
 function validateNotificationChannel(channel: unknown, channelId: string): NotificationChannel {
 	const errors: string[] = [];
 
@@ -1143,6 +1186,16 @@ function validateNotificationChannel(channel: unknown, channelId: string): Notif
 		}
 	}
 
+	if (channel.telegram) {
+		try {
+			result.telegram = validateTelegramConfig(channel.telegram, channelId);
+		} catch (error) {
+			if (error instanceof ConfigValidationError) {
+				throw error;
+			}
+		}
+	}
+
 	return result;
 }
 
@@ -1417,8 +1470,9 @@ function validateNotificationChannelProviders(config: Config): void {
 		const hasEmail = channel.email?.enabled;
 		const hasDiscord = channel.discord?.enabled;
 		const hasNtfy = channel.ntfy?.enabled;
+		const hasTelegram = channel.telegram?.enabled;
 
-		if (!hasEmail && !hasDiscord && !hasNtfy) {
+		if (!hasEmail && !hasDiscord && !hasNtfy && !hasTelegram) {
 			errors.push(`Notification channel '${channelId}' is enabled but has no providers configured`);
 		}
 	}

src/notifications/channel-manager.ts

@@ -1,6 +1,7 @@
 import { EmailProvider } from "./providers/email";
 import { DiscordProvider } from "./providers/discord";
 import { NtfyProvider } from "./providers/ntfy";
+import { TelegramProvider } from "./providers/telegram";
 import { Logger } from "../logger";
 import type { NotificationChannel, NotificationEvent, NotificationProvider } from "../types";
 
@@ -33,6 +34,10 @@ export class NotificationChannelManager {
 				channelProviders.push(new NtfyProvider(channel.ntfy));
 			}
 
+			if (channel.telegram?.enabled) {
+				channelProviders.push(new TelegramProvider(channel.telegram));
+			}
+
 			if (channelProviders.length > 0) {
 				this.providers.set(channelId, channelProviders);
 				Logger.info("Notification channel initialized", {