From 1fad85d48d3d27c1e238ab14ca11a930e0c1cd68 Mon Sep 17 00:00:00 2001
From: Tudor Gradinaru <tudor.rodut@yahoo.com>
Date: Sat, 25 Oct 2025 18:31:01 +0300
Subject: [PATCH] feat: Add Matrix notification support Fixes #3034

---
 .../Pages/v1/Notifications/create/index.jsx   | 58 +++++++++++++++----
 client/src/Pages/v1/Notifications/utils.js    |  5 ++
 client/src/Validation/validation.js           | 34 ++++++++++-
 client/src/locales/en.json                    | 10 ++++
 server/src/db/v1/models/Notification.js       | 12 +++-
 .../v1/infrastructure/networkService.js       | 36 ++++++++++++
 .../notificationProviders/matrix.js           | 34 +++++++++++
 .../v1/infrastructure/notificationService.js  |  9 +++
 server/src/validation/joi.js                  | 36 +++++++++++-
 9 files changed, 219 insertions(+), 15 deletions(-)
 create mode 100644 server/src/service/v1/infrastructure/notificationProviders/matrix.js

diff --git a/client/src/Pages/v1/Notifications/create/index.jsx b/client/src/Pages/v1/Notifications/create/index.jsx
index eb2b04aa6..b1c50493c 100644
--- a/client/src/Pages/v1/Notifications/create/index.jsx
+++ b/client/src/Pages/v1/Notifications/create/index.jsx
@@ -223,18 +223,54 @@ const CreateNotifications = () => {
 						<Typography component="p">{t(DESCRIPTION_MAP[type])}</Typography>
 					</Box>
 					<Stack gap={theme.spacing(12)}>
-						<TextInput
-							label={t(LABEL_MAP[type])}
-							name="address"
-							placeholder={t(PLACEHOLDER_MAP[type])}
-							value={notification.address}
-							onChange={onChange}
-							error={Boolean(errors.address)}
-							helperText={errors["address"]}
-						/>
+						{type === "matrix" ? (
+							<>
+								<TextInput
+									label={t("createNotifications.matrixSettings.homeserverLabel")}
+									name="homeserverUrl"
+									placeholder={t(
+										"createNotifications.matrixSettings.homeserverPlaceholder"
+									)}
+									value={notification.homeserverUrl || ""}
+									onChange={onChange}
+									error={Boolean(errors.homeserverUrl)}
+									helperText={errors["homeserverUrl"]}
+								/>
+								<TextInput
+									label={t("createNotifications.matrixSettings.roomIdLabel")}
+									name="roomId"
+									placeholder={t("createNotifications.matrixSettings.roomIdPlaceholder")}
+									value={notification.roomId || ""}
+									onChange={onChange}
+									error={Boolean(errors.roomId)}
+									helperText={errors["roomId"]}
+								/>
+								<TextInput
+									label={t("createNotifications.matrixSettings.accessTokenLabel")}
+									name="accessToken"
+									type="password"
+									placeholder={t(
+										"createNotifications.matrixSettings.accessTokenPlaceholder"
+									)}
+									value={notification.accessToken || ""}
+									onChange={onChange}
+									error={Boolean(errors.accessToken)}
+									helperText={errors["accessToken"]}
+								/>
+							</>
+						) : (
+							<TextInput
+								label={t(LABEL_MAP[type])}
+								name="address"
+								placeholder={t(PLACEHOLDER_MAP[type])}
+								value={notification.address}
+								onChange={onChange}
+								error={Boolean(errors.address)}
+								helperText={errors["address"]}
+							/>
+						)}
 					</Stack>
-				</ConfigBox>
-
+				</ConfigBox>{" "}
 				<Stack
 					direction="row"
 					justifyContent="flex-end"
diff --git a/client/src/Pages/v1/Notifications/utils.js b/client/src/Pages/v1/Notifications/utils.js
index 0813f6868..2a3d32f4d 100644
--- a/client/src/Pages/v1/Notifications/utils.js
+++ b/client/src/Pages/v1/Notifications/utils.js
@@ -4,6 +4,7 @@ export const NOTIFICATION_TYPES = [
 	{ _id: 3, name: "PagerDuty", value: "pager_duty" },
 	{ _id: 4, name: "Webhook", value: "webhook" },
 	{ _id: 5, name: "Discord", value: "discord" },
+	{ _id: 6, name: "Matrix", value: "matrix" },
 ];
 
 export const TITLE_MAP = {
@@ -12,6 +13,7 @@ export const TITLE_MAP = {
 	pager_duty: "createNotifications.pagerdutySettings.title",
 	webhook: "createNotifications.webhookSettings.title",
 	discord: "createNotifications.discordSettings.title",
+	matrix: "createNotifications.matrixSettings.title",
 };
 
 export const DESCRIPTION_MAP = {
@@ -20,6 +22,7 @@ export const DESCRIPTION_MAP = {
 	pager_duty: "createNotifications.pagerdutySettings.description",
 	webhook: "createNotifications.webhookSettings.description",
 	discord: "createNotifications.discordSettings.description",
+	matrix: "createNotifications.matrixSettings.description",
 };
 
 export const LABEL_MAP = {
@@ -28,6 +31,7 @@ export const LABEL_MAP = {
 	pager_duty: "createNotifications.pagerdutySettings.integrationKeyLabel",
 	webhook: "createNotifications.webhookSettings.webhookLabel",
 	discord: "createNotifications.discordSettings.webhookLabel",
+	matrix: "createNotifications.matrixSettings.homeserverLabel",
 };
 
 export const PLACEHOLDER_MAP = {
@@ -36,4 +40,5 @@ export const PLACEHOLDER_MAP = {
 	pager_duty: "createNotifications.pagerdutySettings.integrationKeyPlaceholder",
 	webhook: "createNotifications.webhookSettings.webhookPlaceholder",
 	discord: "createNotifications.discordSettings.webhookPlaceholder",
+	matrix: "createNotifications.matrixSettings.homeserverPlaceholder",
 };
diff --git a/client/src/Validation/validation.js b/client/src/Validation/validation.js
index 67c267ffd..ce50d96c1 100644
--- a/client/src/Validation/validation.js
+++ b/client/src/Validation/validation.js
@@ -458,7 +458,7 @@ const notificationValidation = joi.object({
 
 	type: joi
 		.string()
-		.valid("email", "webhook", "slack", "discord", "pager_duty")
+		.valid("email", "webhook", "slack", "discord", "pager_duty", "matrix")
 		.required()
 		.messages({
 			"string.empty": "Notification type is required",
@@ -495,8 +495,40 @@ const notificationValidation = joi.object({
 					"string.uri": "Please enter a valid Webhook URL",
 				}),
 			},
+			{
+				is: "matrix",
+				then: joi.string().allow("").optional(),
+			},
 		],
 	}),
+
+	homeserverUrl: joi.when("type", {
+		is: "matrix",
+		then: joi.string().uri().required().messages({
+			"string.empty": "Homeserver URL cannot be empty",
+			"any.required": "Homeserver URL is required",
+			"string.uri": "Please enter a valid Homeserver URL",
+		}),
+		otherwise: joi.string().allow("").optional(),
+	}),
+
+	roomId: joi.when("type", {
+		is: "matrix",
+		then: joi.string().required().messages({
+			"string.empty": "Room ID cannot be empty",
+			"any.required": "Room ID is required",
+		}),
+		otherwise: joi.string().allow("").optional(),
+	}),
+
+	accessToken: joi.when("type", {
+		is: "matrix",
+		then: joi.string().required().messages({
+			"string.empty": "Access Token cannot be empty",
+			"any.required": "Access Token is required",
+		}),
+		otherwise: joi.string().allow("").optional(),
+	}),
 });
 
 const editUserValidation = joi.object({
diff --git a/client/src/locales/en.json b/client/src/locales/en.json
index 13d4a7731..214a28221 100644
--- a/client/src/locales/en.json
+++ b/client/src/locales/en.json
@@ -736,6 +736,16 @@
 			"webhookLabel": "Discord Webhook URL",
 			"webhookPlaceholder": "https://your-server.com/webhook"
 		},
+		"matrixSettings": {
+			"title": "Matrix",
+			"description": "Configure your Matrix notification here",
+			"homeserverLabel": "Homeserver URL",
+			"homeserverPlaceholder": "https://matrix.org",
+			"roomIdLabel": "Room ID",
+			"roomIdPlaceholder": "!QMdRCpUIfLwsfjxye6:home.server",
+			"accessTokenLabel": "Access Token",
+			"accessTokenPlaceholder": "Your Matrix access token"
+		},
 		"webhookSettings": {
 			"title": "Webhook",
 			"description": "Configure your webhook here",
diff --git a/server/src/db/v1/models/Notification.js b/server/src/db/v1/models/Notification.js
index a6a3c7c09..72c716a26 100755
--- a/server/src/db/v1/models/Notification.js
+++ b/server/src/db/v1/models/Notification.js
@@ -16,7 +16,7 @@ const NotificationSchema = mongoose.Schema(
 		},
 		type: {
 			type: String,
-			enum: ["email", "slack", "discord", "webhook", "pager_duty"],
+			enum: ["email", "slack", "discord", "webhook", "pager_duty", "matrix"],
 		},
 		notificationName: {
 			type: String,
@@ -28,6 +28,16 @@ const NotificationSchema = mongoose.Schema(
 		phone: {
 			type: String,
 		},
+		// Matrix-specific fields
+		homeserverUrl: {
+			type: String,
+		},
+		roomId: {
+			type: String,
+		},
+		accessToken: {
+			type: String,
+		},
 	},
 	{
 		timestamps: true,
diff --git a/server/src/service/v1/infrastructure/networkService.js b/server/src/service/v1/infrastructure/networkService.js
index a92b6544b..ade86b1dc 100644
--- a/server/src/service/v1/infrastructure/networkService.js
+++ b/server/src/service/v1/infrastructure/networkService.js
@@ -529,6 +529,42 @@ class NetworkService {
 			throw error;
 		}
 	}
+
+	async requestMatrix({ homeserverUrl, accessToken, roomId, message }) {
+		try {
+			const url = `${homeserverUrl}/_matrix/client/v3/rooms/${roomId}/send/m.room.message?access_token=${accessToken}`;
+			const body = {
+				msgtype: "m.text",
+				body: message,
+				format: "org.matrix.custom.html",
+				formatted_body: message,
+			};
+			const response = await this.axios.post(url, body, {
+				headers: {
+					"Content-Type": "application/json",
+				},
+			});
+
+			return {
+				status: true,
+				code: response.status,
+				message: "Successfully sent Matrix notification",
+			};
+		} catch (error) {
+			this.logger.warn({
+				message: error.message,
+				service: this.SERVICE_NAME,
+				method: "requestMatrix",
+			});
+
+			return {
+				status: false,
+				code: error.response?.status || this.NETWORK_ERROR,
+				message: "Failed to send Matrix notification",
+				payload: error.response?.data,
+			};
+		}
+	}
 }
 
 export default NetworkService;
diff --git a/server/src/service/v1/infrastructure/notificationProviders/matrix.js b/server/src/service/v1/infrastructure/notificationProviders/matrix.js
new file mode 100644
index 000000000..a8b33d4b8
--- /dev/null
+++ b/server/src/service/v1/infrastructure/notificationProviders/matrix.js
@@ -0,0 +1,34 @@
+const SERVICE_NAME = "Matrix";
+
+class Matrix {
+	static SERVICE_NAME = SERVICE_NAME;
+
+	constructor({ networkService, logger }) {
+		this.networkService = networkService;
+		this.logger = logger;
+	}
+
+	get serviceName() {
+		return Matrix.SERVICE_NAME;
+	}
+
+	async send({ friendlyName, homeserverUrl, accessToken, roomId, message, monitorName }) {
+		const title = `Checkmate status for ${monitorName}`;
+		const formattedMessage = `## ${title}\n${message}`;
+		try {
+			await this.networkService.requestMatrix({
+				homeserverUrl,
+				accessToken,
+				roomId,
+				message: formattedMessage,
+			});
+			this.logger.info(`Successfully sent Matrix notification for ${friendlyName}`);
+			return true;
+		} catch (error) {
+			this.logger.error(`Failed to send Matrix notification for ${friendlyName}: ${error.message}`);
+			return false;
+		}
+	}
+}
+
+export default Matrix;
diff --git a/server/src/service/v1/infrastructure/notificationService.js b/server/src/service/v1/infrastructure/notificationService.js
index 6c5b8b25e..8c6fb063f 100644
--- a/server/src/service/v1/infrastructure/notificationService.js
+++ b/server/src/service/v1/infrastructure/notificationService.js
@@ -1,4 +1,5 @@
 const SERVICE_NAME = "NotificationService";
+import Matrix from "./notificationProviders/matrix.js";
 
 class NotificationService {
 	static SERVICE_NAME = SERVICE_NAME;
@@ -46,6 +47,14 @@ class NotificationService {
 
 			return response;
 		}
+		if (type === "matrix") {
+			const { friendlyName, homeserverUrl, accessToken, roomId } = notification;
+			const monitorName = subject;
+			const message = content;
+			const matrix = new Matrix({ networkService: this.networkService, logger: this.logger });
+			const success = await matrix.send({ friendlyName, homeserverUrl, accessToken, roomId, message, monitorName });
+			return success;
+		}
 	};
 
 	async handleNotifications(networkResponse) {
diff --git a/server/src/validation/joi.js b/server/src/validation/joi.js
index 87d2b2a8c..bc88d4567 100755
--- a/server/src/validation/joi.js
+++ b/server/src/validation/joi.js
@@ -575,10 +575,10 @@ const createNotificationBodyValidation = joi.object({
 		"any.required": "Notification name is required",
 	}),
 
-	type: joi.string().valid("email", "webhook", "slack", "discord", "pager_duty").required().messages({
+	type: joi.string().valid("email", "webhook", "slack", "discord", "pager_duty", "matrix").required().messages({
 		"string.empty": "Notification type is required",
 		"any.required": "Notification type is required",
-		"any.only": "Notification type must be email, webhook, or pager_duty",
+		"any.only": "Notification type must be email, webhook, slack, discord, pager_duty, or matrix",
 	}),
 
 	address: joi.when("type", {
@@ -606,8 +606,40 @@ const createNotificationBodyValidation = joi.object({
 					"string.uri": "Please enter a valid Webhook URL",
 				}),
 			},
+			{
+				is: "matrix",
+				then: joi.string().allow("").optional(),
+			},
 		],
 	}),
+
+	homeserverUrl: joi.when("type", {
+		is: "matrix",
+		then: joi.string().uri().required().messages({
+			"string.empty": "Homeserver URL cannot be empty",
+			"any.required": "Homeserver URL is required",
+			"string.uri": "Please enter a valid Homeserver URL",
+		}),
+		otherwise: joi.string().allow("").optional(),
+	}),
+
+	roomId: joi.when("type", {
+		is: "matrix",
+		then: joi.string().required().messages({
+			"string.empty": "Room ID cannot be empty",
+			"any.required": "Room ID is required",
+		}),
+		otherwise: joi.string().allow("").optional(),
+	}),
+
+	accessToken: joi.when("type", {
+		is: "matrix",
+		then: joi.string().required().messages({
+			"string.empty": "Access Token cannot be empty",
+			"any.required": "Access Token is required",
+		}),
+		otherwise: joi.string().allow("").optional(),
+	}),
 });
 
 //****************************************