@checkstack/notification-slack-backend 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @checkstack/notification-slack-backend
+
+## 0.1.0
+
+### Minor Changes
+
+- cf5f245: Added Slack notification provider with incoming webhook support. Features include Block Kit layouts, mrkdwn formatting, action buttons, and color-coded importance attachments.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@checkstack/notification-slack-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,189 @@
+import { describe, it, expect, spyOn } from "bun:test";
+import {
+  slackConfigSchemaV1,
+  slackUserConfigSchema,
+  buildSlackPayload,
+} from "./index";
+
+/**
+ * Unit tests for the Slack Notification Strategy.
+ *
+ * Tests cover:
+ * - Config schema validation
+ * - Block Kit payload building
+ * - Webhook API interaction
+ */
+
+describe("Slack Notification Strategy", () => {
+  // ─────────────────────────────────────────────────────────────────────────
+  // Config Schema Validation
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("config schema", () => {
+    it("accepts empty admin config", () => {
+      const result = slackConfigSchemaV1.parse({});
+      expect(result).toEqual({});
+    });
+
+    it("validates user config - requires webhookUrl", () => {
+      expect(() => {
+        slackUserConfigSchema.parse({});
+      }).toThrow();
+    });
+
+    it("validates user config - requires valid URL", () => {
+      expect(() => {
+        slackUserConfigSchema.parse({ webhookUrl: "not-a-url" });
+      }).toThrow();
+    });
+
+    it("accepts valid user config", () => {
+      const result = slackUserConfigSchema.parse({
+        webhookUrl: "https://hooks.slack.com/services/T00/B00/XXX",
+      });
+      expect(result.webhookUrl).toBe(
+        "https://hooks.slack.com/services/T00/B00/XXX",
+      );
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Block Kit Payload Building
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("payload builder", () => {
+    it("builds payload with title only", () => {
+      const payload = buildSlackPayload({
+        title: "Test Alert",
+        importance: "info",
+      });
+
+      expect(payload.text).toContain("Test Alert");
+      expect(payload.text).toContain("ℹ️");
+      expect(payload.blocks).toHaveLength(1);
+      expect(payload.blocks[0].type).toBe("section");
+      expect(payload.attachments).toHaveLength(1);
+      expect(payload.attachments![0].color).toBe("#3b82f6");
+    });
+
+    it("builds payload with title and body", () => {
+      const payload = buildSlackPayload({
+        title: "System Alert",
+        body: "The system has recovered.",
+        importance: "warning",
+      });
+
+      expect(payload.text).toContain("⚠️");
+      expect(payload.blocks).toHaveLength(2);
+      expect(payload.attachments![0].color).toBe("#f59e0b");
+    });
+
+    it("builds payload with action button", () => {
+      const payload = buildSlackPayload({
+        title: "Incident Created",
+        body: "A new incident requires attention.",
+        importance: "critical",
+        action: {
+          label: "View Incident",
+          url: "https://example.com/incident/123",
+        },
+      });
+
+      expect(payload.text).toContain("🚨");
+      expect(payload.blocks).toHaveLength(3); // header + body + actions
+
+      const actionsBlock = payload.blocks[2];
+      expect(actionsBlock.type).toBe("actions");
+
+      const elements = actionsBlock.elements as Array<Record<string, unknown>>;
+      expect(elements).toHaveLength(1);
+      expect(elements[0].type).toBe("button");
+      expect(elements[0].url).toBe("https://example.com/incident/123");
+    });
+
+    it("uses correct colors for importance levels", () => {
+      const infoPayload = buildSlackPayload({
+        title: "Info",
+        importance: "info",
+      });
+      const warningPayload = buildSlackPayload({
+        title: "Warning",
+        importance: "warning",
+      });
+      const criticalPayload = buildSlackPayload({
+        title: "Critical",
+        importance: "critical",
+      });
+
+      expect(infoPayload.attachments![0].color).toBe("#3b82f6");
+      expect(warningPayload.attachments![0].color).toBe("#f59e0b");
+      expect(criticalPayload.attachments![0].color).toBe("#ef4444");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Webhook API Interaction
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("webhook API interaction", () => {
+    it("sends payload 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("ok", { status: 200 });
+      }) as unknown as typeof fetch);
+
+      try {
+        const webhookUrl = "https://hooks.slack.com/services/T00/B00/XXX";
+        const payload = buildSlackPayload({
+          title: "Test",
+          importance: "info",
+        });
+
+        await fetch(webhookUrl, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(payload),
+        });
+
+        expect(capturedUrl).toBe(webhookUrl);
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.blocks).toBeDefined();
+        expect(parsedBody.text).toContain("Test");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("handles API errors gracefully", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response("invalid_payload", { status: 400 });
+        }) as unknown as typeof fetch,
+      );
+
+      try {
+        const response = await fetch(
+          "https://hooks.slack.com/services/invalid",
+          {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ text: "test" }),
+          },
+        );
+
+        expect(response.ok).toBe(false);
+        expect(response.status).toBe(400);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+import {
+  createBackendPlugin,
+  configString,
+  Versioned,
+  type NotificationStrategy,
+  type NotificationSendContext,
+  type NotificationDeliveryResult,
+  markdownToSlackMrkdwn,
+} from "@checkstack/backend-api";
+import { notificationStrategyExtensionPoint } from "@checkstack/notification-backend";
+import { pluginMetadata } from "./plugin-metadata";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Configuration Schemas
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Admin configuration for Slack strategy.
+ * Optional - no admin config required since users provide their own webhooks.
+ */
+const slackConfigSchemaV1 = z.object({});
+
+type SlackConfig = z.infer<typeof slackConfigSchemaV1>;
+
+/**
+ * User configuration for Slack - users provide their webhook URL.
+ */
+const slackUserConfigSchema = z.object({
+  webhookUrl: configString({}).url().describe("Slack Incoming Webhook URL"),
+});
+
+type SlackUserConfig = z.infer<typeof slackUserConfigSchema>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Instructions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const adminInstructions = `
+## Slack Notifications
+
+Slack notifications are delivered via incoming 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 Slack Incoming Webhook
+
+1. Go to [Slack API Apps](https://api.slack.com/apps) and create a new app (or select existing)
+2. Under **Features**, click **Incoming Webhooks** and toggle it **On**
+3. Click **Add New Webhook to Workspace**
+4. Select a channel where you want to receive notifications
+5. Copy the **Webhook URL** and paste it in the field above
+
+> **Tip**: You can create webhooks for private channels or your own DM channel for personal notifications.
+`.trim();
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Slack Block Kit Builder
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+interface SlackBlockOptions {
+  title: string;
+  body?: string;
+  importance: "info" | "warning" | "critical";
+  action?: { label: string; url: string };
+}
+
+interface SlackPayload {
+  text: string; // Fallback text for notifications
+  blocks: Array<Record<string, unknown>>;
+  attachments?: Array<{ color: string }>;
+}
+
+function buildSlackPayload(options: SlackBlockOptions): SlackPayload {
+  const { title, body, importance, action } = options;
+
+  const importanceEmoji: Record<string, string> = {
+    info: "ℹ️",
+    warning: "⚠️",
+    critical: "🚨",
+  };
+
+  // Attachment colors for importance-based accent
+  const importanceColors: Record<string, string> = {
+    info: "#3b82f6", // Blue
+    warning: "#f59e0b", // Amber
+    critical: "#ef4444", // Red
+  };
+
+  const blocks: Array<Record<string, unknown>> = [
+    // Header section with title
+    {
+      type: "section",
+      text: {
+        type: "mrkdwn",
+        text: `${importanceEmoji[importance]} *${title}*`,
+      },
+    },
+  ];
+
+  // Body section (if provided)
+  if (body) {
+    const mrkdwnBody = markdownToSlackMrkdwn(body);
+    blocks.push({
+      type: "section",
+      text: {
+        type: "mrkdwn",
+        text: mrkdwnBody,
+      },
+    });
+  }
+
+  // Action button (if provided)
+  if (action?.url) {
+    blocks.push({
+      type: "actions",
+      elements: [
+        {
+          type: "button",
+          text: {
+            type: "plain_text",
+            text: action.label,
+            emoji: true,
+          },
+          url: action.url,
+          action_id: "notification_action",
+        },
+      ],
+    });
+  }
+
+  return {
+    text: `${importanceEmoji[importance]} ${title}`, // Fallback for notifications
+    blocks,
+    attachments: [{ color: importanceColors[importance] }],
+  };
+}
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Slack Strategy Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Slack notification strategy using incoming webhooks.
+ */
+const slackStrategy: NotificationStrategy<SlackConfig, SlackUserConfig> = {
+  id: "slack",
+  displayName: "Slack",
+  description: "Send notifications via Slack incoming webhooks",
+  icon: "Hash",
+
+  config: new Versioned({
+    version: 1,
+    schema: slackConfigSchemaV1,
+  }),
+
+  // User-config resolution - users enter their webhook URL
+  contactResolution: { type: "user-config", field: "webhookUrl" },
+
+  userConfig: new Versioned({
+    version: 1,
+    schema: slackUserConfigSchema,
+  }),
+
+  adminInstructions,
+  userInstructions,
+
+  async send(
+    context: NotificationSendContext<SlackConfig, SlackUserConfig>,
+  ): Promise<NotificationDeliveryResult> {
+    const { userConfig, notification, logger } = context;
+
+    if (!userConfig?.webhookUrl) {
+      return {
+        success: false,
+        error: "User has not configured their Slack webhook URL",
+      };
+    }
+
+    try {
+      // Build the Slack payload
+      const payload = buildSlackPayload({
+        title: notification.title,
+        body: notification.body,
+        importance: notification.importance,
+        action: notification.action,
+      });
+
+      // Send to Slack webhook
+      const response = await fetch(userConfig.webhookUrl, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        logger.error("Failed to send Slack message", {
+          status: response.status,
+          error: errorText.slice(0, 500),
+        });
+        return {
+          success: false,
+          error: `Failed to send Slack message: ${response.status}`,
+        };
+      }
+
+      // Slack webhooks return "ok" on success
+      return {
+        success: true,
+      };
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Unknown Slack API error";
+      logger.error("Slack notification error", { error: message });
+      return {
+        success: false,
+        error: `Failed to send Slack notification: ${message}`,
+      };
+    }
+  },
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Get the notification strategy extension point
+    const extensionPoint = env.getExtensionPoint(
+      notificationStrategyExtensionPoint,
+    );
+
+    // Register the Slack strategy with our plugin metadata
+    extensionPoint.addStrategy(slackStrategy, pluginMetadata);
+  },
+});
+
+// Export for testing
+export { slackConfigSchemaV1, slackUserConfigSchema, buildSlackPayload };
+export type { SlackConfig, SlackUserConfig, SlackBlockOptions, SlackPayload };

package/src/plugin-metadata.ts

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

package/tsconfig.json

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