@checkstack/notification-gotify-backend 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @checkstack/notification-gotify-backend
+
+## 0.1.0
+
+### Minor Changes
+
+- cf5f245: Added Gotify notification provider for self-hosted push notifications. Features include priority mapping (info→5, warning→7, critical→10), action URL extras, and configurable server URL.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@checkstack/notification-gotify-backend",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./plugin-metadata": "./src/plugin-metadata.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@checkstack/backend-api": "workspace:*",
+    "@checkstack/common": "workspace:*",
+    "@checkstack/notification-backend": "workspace:*",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "@checkstack/tsconfig": "workspace:*",
+    "typescript": "^5.7.2"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,181 @@
+import { describe, it, expect, spyOn } from "bun:test";
+import {
+  gotifyConfigSchemaV1,
+  gotifyUserConfigSchema,
+  mapImportanceToPriority,
+} from "./index";
+
+/**
+ * Unit tests for the Gotify Notification Strategy.
+ *
+ * Tests cover:
+ * - Config schema validation
+ * - Priority mapping
+ * - REST API interaction
+ */
+
+describe("Gotify Notification Strategy", () => {
+  // ─────────────────────────────────────────────────────────────────────────
+  // Config Schema Validation
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("config schema", () => {
+    it("validates admin config - requires serverUrl", () => {
+      expect(() => {
+        gotifyConfigSchemaV1.parse({});
+      }).toThrow();
+    });
+
+    it("validates admin config - requires valid URL", () => {
+      expect(() => {
+        gotifyConfigSchemaV1.parse({ serverUrl: "not-a-url" });
+      }).toThrow();
+    });
+
+    it("accepts valid admin config", () => {
+      const result = gotifyConfigSchemaV1.parse({
+        serverUrl: "https://gotify.example.com",
+      });
+      expect(result.serverUrl).toBe("https://gotify.example.com");
+    });
+
+    it("validates user config - requires appToken", () => {
+      expect(() => {
+        gotifyUserConfigSchema.parse({});
+      }).toThrow();
+    });
+
+    it("accepts valid user config", () => {
+      const result = gotifyUserConfigSchema.parse({
+        appToken: "A-secret-token-123",
+      });
+      expect(result.appToken).toBe("A-secret-token-123");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Priority Mapping
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("priority mapping", () => {
+    it("maps info to normal priority (5)", () => {
+      expect(mapImportanceToPriority("info")).toBe(5);
+    });
+
+    it("maps warning to high-normal priority (7)", () => {
+      expect(mapImportanceToPriority("warning")).toBe(7);
+    });
+
+    it("maps critical to highest priority (10)", () => {
+      expect(mapImportanceToPriority("critical")).toBe(10);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // REST API Interaction
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("REST API interaction", () => {
+    it("sends message to Gotify server with token", async () => {
+      let capturedBody: string | undefined;
+      let capturedUrl: string | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        url: RequestInfo | URL,
+        options?: RequestInit,
+      ) => {
+        capturedUrl = url.toString();
+        capturedBody = options?.body as string;
+        return new Response(JSON.stringify({ id: 42 }), { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const serverUrl = "https://gotify.example.com";
+        const appToken = "test-token";
+
+        await fetch(`${serverUrl}/message?token=${appToken}`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            title: "Test Alert",
+            message: "Test message body",
+            priority: 5,
+          }),
+        });
+
+        expect(capturedUrl).toContain("gotify.example.com/message");
+        expect(capturedUrl).toContain("token=test-token");
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.title).toBe("Test Alert");
+        expect(parsedBody.message).toBe("Test message body");
+        expect(parsedBody.priority).toBe(5);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("includes extras for action URL", async () => {
+      let capturedBody: string | undefined;
+
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation((async (
+        _url: RequestInfo | URL,
+        options?: RequestInit,
+      ) => {
+        capturedBody = options?.body as string;
+        return new Response(JSON.stringify({ id: 43 }), { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        await fetch("https://gotify.example.com/message?token=test", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            title: "Test",
+            message: "Body",
+            priority: 10,
+            extras: {
+              "client::notification": {
+                click: { url: "https://example.com/action" },
+              },
+            },
+          }),
+        });
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.extras).toBeDefined();
+        expect(parsedBody.extras["client::notification"].click.url).toBe(
+          "https://example.com/action",
+        );
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("handles API errors gracefully", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response(JSON.stringify({ error: "Unauthorized" }), {
+            status: 401,
+          });
+        }) as unknown as typeof fetch,
+      );
+
+      try {
+        const response = await fetch(
+          "https://gotify.example.com/message?token=invalid",
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ title: "Test", message: "Body" }),
+          },
+        );
+
+        expect(response.ok).toBe(false);
+        expect(response.status).toBe(401);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,221 @@
+import { z } from "zod";
+import {
+  createBackendPlugin,
+  configString,
+  Versioned,
+  type NotificationStrategy,
+  type NotificationSendContext,
+  type NotificationDeliveryResult,
+  markdownToPlainText,
+} from "@checkstack/backend-api";
+import { notificationStrategyExtensionPoint } from "@checkstack/notification-backend";
+import { pluginMetadata } from "./plugin-metadata";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Configuration Schemas
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Admin configuration for Gotify strategy.
+ * Admins configure the Gotify server URL.
+ */
+const gotifyConfigSchemaV1 = z.object({
+  serverUrl: configString({})
+    .url()
+    .describe("Gotify server URL (e.g., https://gotify.example.com)"),
+});
+
+type GotifyConfig = z.infer<typeof gotifyConfigSchemaV1>;
+
+/**
+ * User configuration for Gotify - users provide their app token.
+ */
+const gotifyUserConfigSchema = z.object({
+  appToken: configString({ "x-secret": true }).describe(
+    "Gotify Application Token",
+  ),
+});
+
+type GotifyUserConfig = z.infer<typeof gotifyUserConfigSchema>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Instructions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const adminInstructions = `
+## Configure Gotify Server
+
+1. Deploy a [Gotify server](https://gotify.net/) or use an existing instance
+2. Enter the server URL below (e.g., \`https://gotify.example.com\`)
+3. Users will create their own application tokens in the Gotify web UI
+
+> **Note**: Ensure the server URL is accessible from this Checkstack instance.
+`.trim();
+
+const userInstructions = `
+## Get Your Gotify App Token
+
+1. Log into your organization's Gotify server
+2. Go to the **Apps** tab in the web interface
+3. Click **Create Application**
+4. Give it a name (e.g., "Checkstack Notifications")
+5. Copy the generated **Token** and paste it in the field above
+
+> **Tip**: You can customize the app icon in Gotify for easy identification.
+`.trim();
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Priority Mapping
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Maps notification importance to Gotify priority.
+ * Gotify priorities: 0=min, 1-3=low, 4-7=normal, 8-10=high
+ */
+function mapImportanceToPriority(
+  importance: "info" | "warning" | "critical",
+): number {
+  const priorityMap: Record<string, number> = {
+    info: 5, // Normal
+    warning: 7, // High-normal
+    critical: 10, // Highest
+  };
+  return priorityMap[importance];
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Gotify Strategy Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Gotify notification strategy using REST API.
+ */
+const gotifyStrategy: NotificationStrategy<GotifyConfig, GotifyUserConfig> = {
+  id: "gotify",
+  displayName: "Gotify",
+  description: "Send notifications via Gotify self-hosted server",
+  icon: "Bell",
+
+  config: new Versioned({
+    version: 1,
+    schema: gotifyConfigSchemaV1,
+  }),
+
+  // User-config resolution - users enter their app token
+  contactResolution: { type: "user-config", field: "appToken" },
+
+  userConfig: new Versioned({
+    version: 1,
+    schema: gotifyUserConfigSchema,
+  }),
+
+  adminInstructions,
+  userInstructions,
+
+  async send(
+    context: NotificationSendContext<GotifyConfig, GotifyUserConfig>,
+  ): Promise<NotificationDeliveryResult> {
+    const { userConfig, notification, strategyConfig, logger } = context;
+
+    if (!strategyConfig.serverUrl) {
+      return {
+        success: false,
+        error: "Gotify server URL not configured",
+      };
+    }
+
+    if (!userConfig?.appToken) {
+      return {
+        success: false,
+        error: "User has not configured their Gotify app token",
+      };
+    }
+
+    try {
+      // Build message body
+      const message = notification.body
+        ? markdownToPlainText(notification.body)
+        : notification.title;
+
+      // Add action URL to extras if present
+      const extras: Record<string, unknown> = {};
+      if (notification.action?.url) {
+        extras["client::notification"] = {
+          click: { url: notification.action.url },
+        };
+      }
+
+      // Build request URL with token
+      const serverUrl = strategyConfig.serverUrl.replace(/\/$/, "");
+      const url = `${serverUrl}/message?token=${encodeURIComponent(userConfig.appToken)}`;
+
+      // Send to Gotify
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          title: notification.title,
+          message,
+          priority: mapImportanceToPriority(notification.importance),
+          extras: Object.keys(extras).length > 0 ? extras : undefined,
+        }),
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        logger.error("Failed to send Gotify message", {
+          status: response.status,
+          error: errorText.slice(0, 500),
+        });
+        return {
+          success: false,
+          error: `Failed to send Gotify message: ${response.status}`,
+        };
+      }
+
+      const result = (await response.json()) as { id?: number };
+
+      return {
+        success: true,
+        externalId: result.id ? String(result.id) : undefined,
+      };
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Unknown Gotify API error";
+      logger.error("Gotify notification error", { error: message });
+      return {
+        success: false,
+        error: `Failed to send Gotify notification: ${message}`,
+      };
+    }
+  },
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Get the notification strategy extension point
+    const extensionPoint = env.getExtensionPoint(
+      notificationStrategyExtensionPoint,
+    );
+
+    // Register the Gotify strategy with our plugin metadata
+    extensionPoint.addStrategy(gotifyStrategy, pluginMetadata);
+  },
+});
+
+// Export for testing
+export {
+  gotifyConfigSchemaV1,
+  gotifyUserConfigSchema,
+  mapImportanceToPriority,
+};
+export type { GotifyConfig, GotifyUserConfig };

package/src/plugin-metadata.ts

@@ -0,0 +1,5 @@
+import type { PluginMetadata } from "@checkstack/common";
+
+export const pluginMetadata: PluginMetadata = {
+  pluginId: "notification-gotify",
+};

package/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "@checkstack/tsconfig/backend.json"
+}