@checkstack/notification-discord-backend 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @checkstack/notification-discord-backend
+
+## 0.1.0
+
+### Minor Changes
+
+- cf5f245: Added Discord notification provider with webhook support and rich embeds. Features include color-coded importance levels (info/warning/critical), action buttons as embed fields, and emoji indicators.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@checkstack/notification-discord-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,187 @@
+import { describe, it, expect, spyOn } from "bun:test";
+import {
+  discordConfigSchemaV1,
+  discordUserConfigSchema,
+  buildDiscordEmbed,
+} from "./index";
+
+/**
+ * Unit tests for the Discord Notification Strategy.
+ *
+ * Tests cover:
+ * - Config schema validation
+ * - Discord embed building
+ * - Webhook API interaction
+ */
+
+describe("Discord Notification Strategy", () => {
+  // ─────────────────────────────────────────────────────────────────────────
+  // Config Schema Validation
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("config schema", () => {
+    it("accepts empty admin config", () => {
+      const result = discordConfigSchemaV1.parse({});
+      expect(result).toEqual({});
+    });
+
+    it("validates user config - requires webhookUrl", () => {
+      expect(() => {
+        discordUserConfigSchema.parse({});
+      }).toThrow();
+    });
+
+    it("validates user config - requires valid URL", () => {
+      expect(() => {
+        discordUserConfigSchema.parse({ webhookUrl: "not-a-url" });
+      }).toThrow();
+    });
+
+    it("accepts valid user config", () => {
+      const result = discordUserConfigSchema.parse({
+        webhookUrl: "https://discord.com/api/webhooks/123/abc",
+      });
+      expect(result.webhookUrl).toBe(
+        "https://discord.com/api/webhooks/123/abc",
+      );
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Discord Embed Building
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("embed builder", () => {
+    it("builds embed with title only", () => {
+      const embed = buildDiscordEmbed({
+        title: "Test Alert",
+        importance: "info",
+      });
+
+      expect(embed.title).toContain("Test Alert");
+      expect(embed.title).toContain("ℹ️");
+      expect(embed.color).toBe(0x3b_82_f6); // Blue
+      expect(embed.timestamp).toBeDefined();
+    });
+
+    it("builds embed with title and body", () => {
+      const embed = buildDiscordEmbed({
+        title: "System Alert",
+        body: "The system has recovered.",
+        importance: "warning",
+      });
+
+      expect(embed.title).toContain("⚠️");
+      expect(embed.title).toContain("System Alert");
+      expect(embed.description).toBe("The system has recovered.");
+      expect(embed.color).toBe(0xf5_9e_0b); // Amber
+    });
+
+    it("builds embed with action button as field", () => {
+      const embed = buildDiscordEmbed({
+        title: "Incident Created",
+        body: "A new incident requires attention.",
+        importance: "critical",
+        action: {
+          label: "View Incident",
+          url: "https://example.com/incident/123",
+        },
+      });
+
+      expect(embed.title).toContain("🚨");
+      expect(embed.color).toBe(0xef_44_44); // Red
+      expect(embed.fields).toHaveLength(1);
+      expect(embed.fields![0].name).toBe("View Incident");
+      expect(embed.fields![0].value).toContain(
+        "https://example.com/incident/123",
+      );
+    });
+
+    it("uses correct colors for importance levels", () => {
+      const infoEmbed = buildDiscordEmbed({
+        title: "Info",
+        importance: "info",
+      });
+      const warningEmbed = buildDiscordEmbed({
+        title: "Warning",
+        importance: "warning",
+      });
+      const criticalEmbed = buildDiscordEmbed({
+        title: "Critical",
+        importance: "critical",
+      });
+
+      expect(infoEmbed.color).toBe(0x3b_82_f6);
+      expect(warningEmbed.color).toBe(0xf5_9e_0b);
+      expect(criticalEmbed.color).toBe(0xef_44_44);
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Webhook API Interaction
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("webhook API interaction", () => {
+    it("sends embed to webhook URL", 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(null, { status: 204 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const webhookUrl = "https://discord.com/api/webhooks/123/abc";
+        const embed = buildDiscordEmbed({
+          title: "Test",
+          importance: "info",
+        });
+
+        await fetch(webhookUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ embeds: [embed] }),
+        });
+
+        expect(capturedUrl).toBe(webhookUrl);
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.embeds).toHaveLength(1);
+        expect(parsedBody.embeds[0].title).toContain("Test");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("handles API errors gracefully", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response(JSON.stringify({ message: "Invalid webhook" }), {
+            status: 404,
+          });
+        }) as unknown as typeof fetch,
+      );
+
+      try {
+        const response = await fetch(
+          "https://discord.com/api/webhooks/invalid",
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ embeds: [] }),
+          },
+        );
+
+        expect(response.ok).toBe(false);
+        expect(response.status).toBe(404);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,230 @@
+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 Discord strategy.
+ * Optional - no admin config required since users provide their own webhooks.
+ */
+const discordConfigSchemaV1 = z.object({});
+
+type DiscordConfig = z.infer<typeof discordConfigSchemaV1>;
+
+/**
+ * User configuration for Discord - users provide their webhook URL.
+ */
+const discordUserConfigSchema = z.object({
+  webhookUrl: configString({}).url().describe("Discord Webhook URL"),
+});
+
+type DiscordUserConfig = z.infer<typeof discordUserConfigSchema>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Instructions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const adminInstructions = `
+## Discord Notifications
+
+Discord notifications are delivered via webhooks that users configure individually.
+Each user provides their own webhook URL in their notification settings.
+
+No admin configuration is required for this strategy.
+`.trim();
+
+const userInstructions = `
+## Create a Discord Webhook
+
+1. Open Discord and go to the channel where you want notifications
+2. Click the **gear icon** (Edit Channel) next to the channel name
+3. Go to **Integrations** → **Webhooks** → **New Webhook**
+4. Give your webhook a name (e.g., "Checkstack Alerts")
+5. Click **Copy Webhook URL** and paste it in the field above
+
+> **Privacy Note**: This webhook URL is private to you. Only use webhooks for channels you control.
+`.trim();
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Discord Embed Builder
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+interface DiscordEmbedOptions {
+  title: string;
+  body?: string;
+  importance: "info" | "warning" | "critical";
+  action?: { label: string; url: string };
+}
+
+interface DiscordEmbed {
+  title: string;
+  description?: string;
+  color: number;
+  fields?: Array<{ name: string; value: string; inline?: boolean }>;
+  timestamp?: string;
+}
+
+function buildDiscordEmbed(options: DiscordEmbedOptions): DiscordEmbed {
+  const { title, body, importance, action } = options;
+
+  // Discord colors are decimal values
+  const importanceColors: Record<string, number> = {
+    info: 0x3B_82_F6, // Blue
+    warning: 0xF5_9E_0B, // Amber
+    critical: 0xEF_44_44, // Red
+  };
+
+  const importanceEmoji: Record<string, string> = {
+    info: "ℹ️",
+    warning: "⚠️",
+    critical: "🚨",
+  };
+
+  const embed: DiscordEmbed = {
+    title: `${importanceEmoji[importance]} ${title}`,
+    color: importanceColors[importance],
+    timestamp: new Date().toISOString(),
+  };
+
+  if (body) {
+    // Convert markdown to plain text for better Discord compatibility
+    embed.description = markdownToPlainText(body);
+  }
+
+  if (action?.url) {
+    embed.fields = [
+      {
+        name: action.label,
+        value: `[Click here](${action.url})`,
+        inline: false,
+      },
+    ];
+  }
+
+  return embed;
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Discord Strategy Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Discord notification strategy using webhooks.
+ */
+const discordStrategy: NotificationStrategy<DiscordConfig, DiscordUserConfig> =
+  {
+    id: "discord",
+    displayName: "Discord",
+    description: "Send notifications via Discord webhooks",
+    icon: "MessageCircle",
+
+    config: new Versioned({
+      version: 1,
+      schema: discordConfigSchemaV1,
+    }),
+
+    // User-config resolution - users enter their webhook URL
+    contactResolution: { type: "user-config", field: "webhookUrl" },
+
+    userConfig: new Versioned({
+      version: 1,
+      schema: discordUserConfigSchema,
+    }),
+
+    adminInstructions,
+    userInstructions,
+
+    async send(
+      context: NotificationSendContext<DiscordConfig, DiscordUserConfig>,
+    ): Promise<NotificationDeliveryResult> {
+      const { userConfig, notification, logger } = context;
+
+      if (!userConfig?.webhookUrl) {
+        return {
+          success: false,
+          error: "User has not configured their Discord webhook URL",
+        };
+      }
+
+      try {
+        // Build the embed
+        const embed = buildDiscordEmbed({
+          title: notification.title,
+          body: notification.body,
+          importance: notification.importance,
+          action: notification.action,
+        });
+
+        // Send to Discord webhook
+        const response = await fetch(userConfig.webhookUrl, {
+          method: "POST",
+          headers: {
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            embeds: [embed],
+          }),
+          signal: AbortSignal.timeout(10_000),
+        });
+
+        if (!response.ok) {
+          const errorText = await response.text();
+          logger.error("Failed to send Discord message", {
+            status: response.status,
+            error: errorText.slice(0, 500),
+          });
+          return {
+            success: false,
+            error: `Failed to send Discord message: ${response.status}`,
+          };
+        }
+
+        // Discord webhooks return 204 No Content on success
+        return {
+          success: true,
+        };
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "Unknown Discord API error";
+        logger.error("Discord notification error", { error: message });
+        return {
+          success: false,
+          error: `Failed to send Discord notification: ${message}`,
+        };
+      }
+    },
+  };
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Get the notification strategy extension point
+    const extensionPoint = env.getExtensionPoint(
+      notificationStrategyExtensionPoint,
+    );
+
+    // Register the Discord strategy with our plugin metadata
+    extensionPoint.addStrategy(discordStrategy, pluginMetadata);
+  },
+});
+
+// Export for testing
+export { discordConfigSchemaV1, discordUserConfigSchema, buildDiscordEmbed };
+export type { DiscordConfig, DiscordUserConfig, DiscordEmbedOptions };

package/src/plugin-metadata.ts

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

package/tsconfig.json

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