@checkstack/notification-pushover-backend 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @checkstack/notification-pushover-backend
+
+## 0.1.0
+
+### Minor Changes
+
+- cf5f245: Added Pushover notification provider for mobile push notifications. Features include priority mapping (info→0, warning→1, critical→2 emergency), retry/expire for emergency alerts, and supplementary URL support.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@checkstack/notification-pushover-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,233 @@
+import { describe, it, expect, spyOn } from "bun:test";
+import {
+  pushoverConfigSchemaV1,
+  pushoverUserConfigSchema,
+  mapImportanceToPriority,
+  PUSHOVER_API_URL,
+  EMERGENCY_RETRY_SECONDS,
+  EMERGENCY_EXPIRE_SECONDS,
+} from "./index";
+
+/**
+ * Unit tests for the Pushover Notification Strategy.
+ *
+ * Tests cover:
+ * - Config schema validation
+ * - Priority mapping
+ * - REST API interaction
+ * - Emergency notification parameters
+ */
+
+describe("Pushover Notification Strategy", () => {
+  // ─────────────────────────────────────────────────────────────────────────
+  // Config Schema Validation
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("config schema", () => {
+    it("validates admin config - requires apiToken", () => {
+      expect(() => {
+        pushoverConfigSchemaV1.parse({});
+      }).toThrow();
+    });
+
+    it("accepts valid admin config", () => {
+      const result = pushoverConfigSchemaV1.parse({
+        apiToken: "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5",
+      });
+      expect(result.apiToken).toBe("a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5");
+    });
+
+    it("validates user config - requires userKey", () => {
+      expect(() => {
+        pushoverUserConfigSchema.parse({});
+      }).toThrow();
+    });
+
+    it("accepts valid user config", () => {
+      const result = pushoverUserConfigSchema.parse({
+        userKey: "u1s2e3r4k5e6y7-abcdefg",
+      });
+      expect(result.userKey).toBe("u1s2e3r4k5e6y7-abcdefg");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Priority Mapping
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("priority mapping", () => {
+    it("maps info to normal priority (0)", () => {
+      expect(mapImportanceToPriority("info")).toBe(0);
+    });
+
+    it("maps warning to high priority (1)", () => {
+      expect(mapImportanceToPriority("warning")).toBe(1);
+    });
+
+    it("maps critical to emergency priority (2)", () => {
+      expect(mapImportanceToPriority("critical")).toBe(2);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Emergency Parameters
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("emergency parameters", () => {
+    it("has correct retry interval", () => {
+      expect(EMERGENCY_RETRY_SECONDS).toBe(60);
+    });
+
+    it("has correct expire duration", () => {
+      expect(EMERGENCY_EXPIRE_SECONDS).toBe(3600);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // REST API Interaction
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("REST API interaction", () => {
+    it("sends message to Pushover API", 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({ status: 1, request: "abc123" }), {
+          status: 200,
+        });
+      }) as unknown as typeof fetch);
+
+      try {
+        await fetch(PUSHOVER_API_URL, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            token: "api-token",
+            user: "user-key",
+            title: "Test Alert",
+            message: "Test message body",
+            priority: 0,
+            html: 1,
+          }),
+        });
+
+        expect(capturedUrl).toBe(PUSHOVER_API_URL);
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.token).toBe("api-token");
+        expect(parsedBody.user).toBe("user-key");
+        expect(parsedBody.title).toBe("Test Alert");
+        expect(parsedBody.priority).toBe(0);
+        expect(parsedBody.html).toBe(1);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("includes URL parameters for action", 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({ status: 1, request: "def456" }), {
+          status: 200,
+        });
+      }) as unknown as typeof fetch);
+
+      try {
+        await fetch(PUSHOVER_API_URL, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            token: "api-token",
+            user: "user-key",
+            title: "Incident",
+            message: "View incident",
+            priority: 1,
+            html: 1,
+            url: "https://example.com/incident/123",
+            url_title: "View Incident",
+          }),
+        });
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.url).toBe("https://example.com/incident/123");
+        expect(parsedBody.url_title).toBe("View Incident");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("includes retry/expire for emergency priority", 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({ status: 1, request: "ghi789", receipt: "rcpt123" }),
+          { status: 200 },
+        );
+      }) as unknown as typeof fetch);
+
+      try {
+        await fetch(PUSHOVER_API_URL, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({
+            token: "api-token",
+            user: "user-key",
+            title: "Critical Alert",
+            message: "Immediate attention required",
+            priority: 2,
+            html: 1,
+            retry: EMERGENCY_RETRY_SECONDS,
+            expire: EMERGENCY_EXPIRE_SECONDS,
+          }),
+        });
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.priority).toBe(2);
+        expect(parsedBody.retry).toBe(60);
+        expect(parsedBody.expire).toBe(3600);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("handles API errors gracefully", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response(
+            JSON.stringify({ status: 0, errors: ["invalid token"] }),
+            { status: 400 },
+          );
+        }) as unknown as typeof fetch,
+      );
+
+      try {
+        const response = await fetch(PUSHOVER_API_URL, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ token: "invalid", user: "key" }),
+        });
+
+        expect(response.ok).toBe(false);
+        expect(response.status).toBe(400);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,256 @@
+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 Pushover strategy.
+ * Admins register an app at pushover.net and provide the API token.
+ */
+const pushoverConfigSchemaV1 = z.object({
+  apiToken: configString({ "x-secret": true }).describe(
+    "Pushover Application API Token",
+  ),
+});
+
+type PushoverConfig = z.infer<typeof pushoverConfigSchemaV1>;
+
+/**
+ * User configuration for Pushover - users provide their user key.
+ */
+const pushoverUserConfigSchema = z.object({
+  userKey: configString({ "x-secret": true }).describe("Pushover User Key"),
+});
+
+type PushoverUserConfig = z.infer<typeof pushoverUserConfigSchema>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Instructions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const adminInstructions = `
+## Register a Pushover Application
+
+1. Go to [Pushover](https://pushover.net/) and sign in
+2. Scroll to the bottom and click **Create an Application/API Token**
+3. Fill in the application details:
+   - **Name**: e.g., "Checkstack Notifications"
+   - **Type**: Application
+   - **Description**: (optional)
+4. Click **Create Application**
+5. Copy the **API Token/Key** and paste it in the field above
+
+> **Note**: The API token is shared across all users. Each user provides their own User Key.
+`.trim();
+
+const userInstructions = `
+## Get Your Pushover User Key
+
+1. Go to [Pushover](https://pushover.net/) and sign in (or create an account)
+2. Your **User Key** is displayed on the main page after login
+3. Copy the key and paste it in the field above
+
+> **Tip**: Make sure you have the Pushover app installed on your device to receive notifications.
+`.trim();
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Priority Mapping
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Maps notification importance to Pushover priority.
+ * Pushover priorities: -2=lowest, -1=low, 0=normal, 1=high, 2=emergency
+ */
+function mapImportanceToPriority(
+  importance: "info" | "warning" | "critical",
+): number {
+  const priorityMap: Record<string, number> = {
+    info: 0, // Normal
+    warning: 1, // High (bypasses quiet hours)
+    critical: 2, // Emergency (requires acknowledgment)
+  };
+  return priorityMap[importance];
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Pushover API Constants
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const PUSHOVER_API_URL = "https://api.pushover.net/1/messages.json";
+
+// Emergency priority parameters
+const EMERGENCY_RETRY_SECONDS = 60; // Retry every 60 seconds
+const EMERGENCY_EXPIRE_SECONDS = 3600; // Expire after 1 hour
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Pushover Strategy Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Pushover notification strategy using REST API.
+ */
+const pushoverStrategy: NotificationStrategy<
+  PushoverConfig,
+  PushoverUserConfig
+> = {
+  id: "pushover",
+  displayName: "Pushover",
+  description: "Send notifications via Pushover mobile app",
+  icon: "Smartphone",
+
+  config: new Versioned({
+    version: 1,
+    schema: pushoverConfigSchemaV1,
+  }),
+
+  // User-config resolution - users enter their user key
+  contactResolution: { type: "user-config", field: "userKey" },
+
+  userConfig: new Versioned({
+    version: 1,
+    schema: pushoverUserConfigSchema,
+  }),
+
+  adminInstructions,
+  userInstructions,
+
+  async send(
+    context: NotificationSendContext<PushoverConfig, PushoverUserConfig>,
+  ): Promise<NotificationDeliveryResult> {
+    const { userConfig, notification, strategyConfig, logger } = context;
+
+    if (!strategyConfig.apiToken) {
+      return {
+        success: false,
+        error: "Pushover API token not configured",
+      };
+    }
+
+    if (!userConfig?.userKey) {
+      return {
+        success: false,
+        error: "User has not configured their Pushover user key",
+      };
+    }
+
+    try {
+      const priority = mapImportanceToPriority(notification.importance);
+
+      // Build message body
+      const message = notification.body
+        ? markdownToPlainText(notification.body)
+        : notification.title;
+
+      // Build request body
+      const body: Record<string, string | number> = {
+        token: strategyConfig.apiToken,
+        user: userConfig.userKey,
+        title: notification.title,
+        message,
+        priority,
+        html: 1, // Enable HTML formatting
+      };
+
+      // Add action URL if present
+      if (notification.action?.url) {
+        body.url = notification.action.url;
+        body.url_title = notification.action.label;
+      }
+
+      // Emergency priority requires retry and expire parameters
+      if (priority === 2) {
+        body.retry = EMERGENCY_RETRY_SECONDS;
+        body.expire = EMERGENCY_EXPIRE_SECONDS;
+      }
+
+      // Send to Pushover
+      const response = await fetch(PUSHOVER_API_URL, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        logger.error("Failed to send Pushover message", {
+          status: response.status,
+          error: errorText.slice(0, 500),
+        });
+        return {
+          success: false,
+          error: `Failed to send Pushover message: ${response.status}`,
+        };
+      }
+
+      const result = (await response.json()) as {
+        status: number;
+        request: string;
+        receipt?: string;
+      };
+
+      if (result.status !== 1) {
+        return {
+          success: false,
+          error: "Pushover API returned error status",
+        };
+      }
+
+      return {
+        success: true,
+        externalId: result.receipt ?? result.request,
+      };
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Unknown Pushover API error";
+      logger.error("Pushover notification error", { error: message });
+      return {
+        success: false,
+        error: `Failed to send Pushover notification: ${message}`,
+      };
+    }
+  },
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Get the notification strategy extension point
+    const extensionPoint = env.getExtensionPoint(
+      notificationStrategyExtensionPoint,
+    );
+
+    // Register the Pushover strategy with our plugin metadata
+    extensionPoint.addStrategy(pushoverStrategy, pluginMetadata);
+  },
+});
+
+// Export for testing
+export {
+  pushoverConfigSchemaV1,
+  pushoverUserConfigSchema,
+  mapImportanceToPriority,
+  PUSHOVER_API_URL,
+  EMERGENCY_RETRY_SECONDS,
+  EMERGENCY_EXPIRE_SECONDS,
+};
+export type { PushoverConfig, PushoverUserConfig };

package/src/plugin-metadata.ts

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

package/tsconfig.json

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