feat: add ntfy integration (#2900)

Co-authored-by: Meier Lukas <meierschlumpf@gmail.com>

packages/integrations/src/base/creator.ts

@@ -21,6 +21,7 @@ import { ReadarrIntegration } from "../media-organizer/readarr/readarr-integrati
 import { SonarrIntegration } from "../media-organizer/sonarr/sonarr-integration";
 import { TdarrIntegration } from "../media-transcoding/tdarr-integration";
 import { NextcloudIntegration } from "../nextcloud/nextcloud.integration";
+import { NTFYIntegration } from "../ntfy/ntfy-integration";
 import { OpenMediaVaultIntegration } from "../openmediavault/openmediavault-integration";
 import { OverseerrIntegration } from "../overseerr/overseerr-integration";
 import { createPiHoleIntegrationAsync } from "../pi-hole/pi-hole-integration-factory";
@@ -92,6 +93,7 @@ export const integrationCreators = {
   emby: EmbyIntegration,
   nextcloud: NextcloudIntegration,
   unifiController: UnifiControllerIntegration,
+  ntfy: NTFYIntegration,
 } satisfies Record<IntegrationKind, IntegrationInstance | [(input: IntegrationInput) => Promise<Integration>]>;
 
 type IntegrationInstanceOfKind<TKind extends keyof typeof integrationCreators> = {

packages/integrations/src/index.ts

@@ -1,26 +1,27 @@
 // General integrations
 export { AdGuardHomeIntegration } from "./adguard-home/adguard-home-integration";
+export { Aria2Integration } from "./download-client/aria2/aria2-integration";
 export { DelugeIntegration } from "./download-client/deluge/deluge-integration";
 export { NzbGetIntegration } from "./download-client/nzbget/nzbget-integration";
 export { QBitTorrentIntegration } from "./download-client/qbittorrent/qbittorrent-integration";
 export { SabnzbdIntegration } from "./download-client/sabnzbd/sabnzbd-integration";
 export { TransmissionIntegration } from "./download-client/transmission/transmission-integration";
-export { Aria2Integration } from "./download-client/aria2/aria2-integration";
 export { HomeAssistantIntegration } from "./homeassistant/homeassistant-integration";
 export { DownloadClientIntegration } from "./interfaces/downloads/download-client-integration";
 export { JellyfinIntegration } from "./jellyfin/jellyfin-integration";
 export { JellyseerrIntegration } from "./jellyseerr/jellyseerr-integration";
+export { LidarrIntegration } from "./media-organizer/lidarr/lidarr-integration";
 export { RadarrIntegration } from "./media-organizer/radarr/radarr-integration";
+export { ReadarrIntegration } from "./media-organizer/readarr/readarr-integration";
 export { SonarrIntegration } from "./media-organizer/sonarr/sonarr-integration";
+export { NextcloudIntegration } from "./nextcloud/nextcloud.integration";
+export { NTFYIntegration } from "./ntfy/ntfy-integration";
 export { OpenMediaVaultIntegration } from "./openmediavault/openmediavault-integration";
 export { OverseerrIntegration } from "./overseerr/overseerr-integration";
 export { PiHoleIntegrationV5 } from "./pi-hole/v5/pi-hole-integration-v5";
 export { PiHoleIntegrationV6 } from "./pi-hole/v6/pi-hole-integration-v6";
 export { PlexIntegration } from "./plex/plex-integration";
 export { ProwlarrIntegration } from "./prowlarr/prowlarr-integration";
-export { LidarrIntegration } from "./media-organizer/lidarr/lidarr-integration";
-export { ReadarrIntegration } from "./media-organizer/readarr/readarr-integration";
-export { NextcloudIntegration } from "./nextcloud/nextcloud.integration";
 
 // Types
 export type { IntegrationInput } from "./base/integration";
@@ -34,6 +35,7 @@ export type { StreamSession } from "./interfaces/media-server/session";
 export type { TdarrQueue } from "./interfaces/media-transcoding/queue";
 export type { TdarrPieSegment, TdarrStatistics } from "./interfaces/media-transcoding/statistics";
 export type { TdarrWorker } from "./interfaces/media-transcoding/workers";
+export type { Notification } from "./interfaces/notifications/notification";
 
 // Schemas
 export { downloadClientItemSchema } from "./interfaces/downloads/download-client-items";

packages/integrations/src/interfaces/notifications/notification.ts

@@ -0,0 +1,6 @@
+export interface Notification {
+  id: string;
+  time: Date;
+  title: string;
+  body: string;
+}

packages/integrations/src/interfaces/notifications/notifications-integration.ts

@@ -0,0 +1,6 @@
+import { Integration } from "../../base/integration";
+import type { Notification } from "./notification";
+
+export abstract class NotificationsIntegration extends Integration {
+  public abstract getNotificationsAsync(): Promise<Notification[]>;
+}

packages/integrations/src/ntfy/ntfy-integration.ts

@@ -0,0 +1,65 @@
+import { fetchWithTrustedCertificatesAsync } from "@homarr/certificates/server";
+import { ResponseError } from "@homarr/common/server";
+
+import type { IntegrationTestingInput } from "../base/integration";
+import type { TestingResult } from "../base/test-connection/test-connection-service";
+import type { Notification } from "../interfaces/notifications/notification";
+import { NotificationsIntegration } from "../interfaces/notifications/notifications-integration";
+import { ntfyNotificationSchema } from "./ntfy-schema";
+
+export class NTFYIntegration extends NotificationsIntegration {
+  public async testingAsync(input: IntegrationTestingInput): Promise<TestingResult> {
+    await input.fetchAsync(this.url("/v1/account"), { headers: this.getHeaders() });
+    return { success: true };
+  }
+
+  private getTopicURL() {
+    return this.url(`/${encodeURIComponent(super.getSecretValue("topic"))}/json`, { poll: 1 });
+  }
+  private getHeaders() {
+    return this.hasSecretValue("apiKey") ? { Authorization: `Bearer ${super.getSecretValue("apiKey")}` } : {};
+  }
+
+  public async getNotificationsAsync() {
+    const url = this.getTopicURL();
+    const notifications = await Promise.all(
+      (
+        await fetchWithTrustedCertificatesAsync(url, { headers: this.getHeaders() })
+          .then((response) => {
+            if (!response.ok) throw new ResponseError(response);
+            return response.text();
+          })
+          .catch((error) => {
+            if (error instanceof Error) throw error;
+            else {
+              throw new Error("Error communicating with ntfy");
+            }
+          })
+      )
+        // response is provided as individual lines of JSON
+        .split("\n")
+        .map(async (line) => {
+          // ignore empty lines
+          if (line.length === 0) return null;
+
+          const json = JSON.parse(line) as unknown;
+          const parsed = await ntfyNotificationSchema.parseAsync(json);
+          if (parsed.event === "message") return parsed;
+          // ignore non-event messages
+          else return null;
+        }),
+    );
+
+    return notifications
+      .filter((notification) => notification !== null)
+      .map((notification): Notification => {
+        const topicURL = this.url(`/${notification.topic}`);
+        return {
+          id: notification.id,
+          time: new Date(notification.time * 1000),
+          title: notification.title ?? topicURL.hostname + topicURL.pathname,
+          body: notification.message,
+        };
+      });
+  }
+}

packages/integrations/src/ntfy/ntfy-schema.ts

@@ -0,0 +1,12 @@
+import { z } from "zod";
+
+// There are more properties, see: https://docs.ntfy.sh/subscribe/api/#json-message-format
+// Not all properties are required for this use case.
+export const ntfyNotificationSchema = z.object({
+  id: z.string(),
+  time: z.number(),
+  event: z.string(), // we only care about "message"
+  topic: z.string(),
+  title: z.optional(z.string()),
+  message: z.string(),
+});