@checkstack/notification-webex-backend 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# @checkstack/notification-webex-backend
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/backend-api@0.0.2
+  - @checkstack/common@0.0.2
+  - @checkstack/notification-backend@0.0.2
+
+## 0.1.0
+
+### Minor Changes
+
+- 4c5aa9e: Add Webex notification strategy - sends alerts to users via Webex direct messages
+
+  - Bot token configured by admin (long-lived tokens from developer.webex.com)
+  - Users configure their Webex Person ID to receive notifications
+  - Supports markdown formatting with importance emojis and action links
+  - Includes admin and user setup instructions
+
+### Patch Changes
+
+- Updated dependencies [b4eb432]
+- Updated dependencies [a65e002]
+  - @checkstack/backend-api@1.1.0
+  - @checkstack/notification-backend@0.1.2
+  - @checkstack/common@0.2.0

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@checkstack/notification-webex-backend",
+  "version": "0.0.2",
+  "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"
+  },
+  "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,294 @@
+import { describe, it, expect, beforeEach, mock, spyOn } from "bun:test";
+import type { Logger } from "@checkstack/backend-api";
+
+// Re-export for testing since we can't import directly from index.ts without side effects
+// We'll test the schemas and strategy logic indirectly through the provider
+
+/**
+ * Unit tests for the Webex Notification Strategy.
+ *
+ * Tests cover:
+ * - Config schema validation
+ * - Successful message delivery
+ * - Error handling
+ * - Message formatting
+ */
+
+// Mock logger
+const mockLogger: Logger = {
+  debug: mock(() => {}),
+  info: mock(() => {}),
+  warn: mock(() => {}),
+  error: mock(() => {}),
+};
+
+describe("Webex Notification Strategy", () => {
+  beforeEach(() => {
+    (mockLogger.debug as ReturnType<typeof mock>).mockClear();
+    (mockLogger.info as ReturnType<typeof mock>).mockClear();
+    (mockLogger.warn as ReturnType<typeof mock>).mockClear();
+    (mockLogger.error as ReturnType<typeof mock>).mockClear();
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Config Schema Validation
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("config schema", () => {
+    // Import schemas inline to avoid plugin initialization side effects
+    it("validates admin config - requires bot token", async () => {
+      const { z } = await import("zod");
+      const { configString } = await import("@checkstack/backend-api");
+
+      const webexConfigSchemaV1 = z.object({
+        botToken: configString({ "x-secret": true }).describe(
+          "Webex Bot Access Token"
+        ),
+      });
+
+      // Missing bot token should fail
+      expect(() => {
+        webexConfigSchemaV1.parse({});
+      }).toThrow();
+
+      // Valid config should pass
+      const result = webexConfigSchemaV1.parse({
+        botToken: "test-bot-token-123",
+      });
+      expect(result.botToken).toBe("test-bot-token-123");
+    });
+
+    it("validates user config - requires person ID", async () => {
+      const { z } = await import("zod");
+
+      const webexUserConfigSchema = z.object({
+        personId: z.string().min(1).describe("Your Webex Person ID"),
+      });
+
+      // Empty person ID should fail
+      expect(() => {
+        webexUserConfigSchema.parse({ personId: "" });
+      }).toThrow();
+
+      // Missing person ID should fail
+      expect(() => {
+        webexUserConfigSchema.parse({});
+      }).toThrow();
+
+      // Valid config should pass
+      const result = webexUserConfigSchema.parse({
+        personId: "Y2lzY29zcGFyazovL3VzL1BFT1BMRS8xMjM0NTY=",
+      });
+      expect(result.personId).toBe("Y2lzY29zcGFyazovL3VzL1BFT1BMRS8xMjM0NTY=");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Message Delivery
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("message delivery", () => {
+    it("sends message with correct payload structure", async () => {
+      let capturedBody: string | undefined;
+      let capturedHeaders: Record<string, 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;
+        capturedHeaders = options?.headers as Record<string, string>;
+        return new Response(JSON.stringify({ id: "msg-123" }), {
+          status: 200,
+        });
+      }) as unknown as typeof fetch);
+
+      try {
+        // Simulate what the send method does
+        const botToken = "test-bot-token";
+        const personId = "test-person-id";
+        const markdown =
+          "ℹ️ **Test Title**\n\nTest body\n\n[View](https://example.com)";
+
+        const response = await fetch("https://webexapis.com/v1/messages", {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${botToken}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            toPersonId: personId,
+            markdown,
+          }),
+        });
+
+        expect(capturedUrl).toBe("https://webexapis.com/v1/messages");
+        expect(capturedHeaders?.["Authorization"]).toBe(`Bearer ${botToken}`);
+        expect(capturedHeaders?.["Content-Type"]).toBe("application/json");
+
+        const parsedBody = JSON.parse(capturedBody!);
+        expect(parsedBody.toPersonId).toBe(personId);
+        expect(parsedBody.markdown).toContain("**Test Title**");
+        expect(parsedBody.markdown).toContain("Test body");
+        expect(parsedBody.markdown).toContain("[View](https://example.com)");
+
+        expect(response.ok).toBe(true);
+        const result = await response.json();
+        expect(result.id).toBe("msg-123");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("formats messages with correct importance emoji", async () => {
+      const importanceEmoji = {
+        info: "ℹ️",
+        warning: "⚠️",
+        critical: "🚨",
+      };
+
+      // Test each importance level
+      for (const [importance, emoji] of Object.entries(importanceEmoji)) {
+        const title = "Test Alert";
+        const markdown = `${emoji} **${title}**`;
+
+        expect(markdown).toContain(emoji);
+        expect(markdown).toContain(`**${title}**`);
+      }
+    });
+
+    it("handles API errors gracefully", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          return new Response(
+            JSON.stringify({ message: "Invalid personId", trackingId: "123" }),
+            { status: 400 }
+          );
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        const response = await fetch("https://webexapis.com/v1/messages", {
+          method: "POST",
+          headers: {
+            Authorization: "Bearer test-token",
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            toPersonId: "invalid-person-id",
+            markdown: "Test message",
+          }),
+        });
+
+        expect(response.ok).toBe(false);
+        expect(response.status).toBe(400);
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("handles network errors", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          throw new Error("Network error: ECONNREFUSED");
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        await expect(
+          fetch("https://webexapis.com/v1/messages", {
+            method: "POST",
+            headers: {
+              Authorization: "Bearer test-token",
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+              toPersonId: "test-person",
+              markdown: "Test",
+            }),
+          })
+        ).rejects.toThrow("ECONNREFUSED");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+
+    it("handles timeout errors", async () => {
+      const mockFetch = spyOn(globalThis, "fetch").mockImplementation(
+        (async () => {
+          throw new Error("The operation was aborted due to timeout");
+        }) as unknown as typeof fetch
+      );
+
+      try {
+        await expect(
+          fetch("https://webexapis.com/v1/messages", {
+            method: "POST",
+            signal: AbortSignal.timeout(10_000),
+            headers: {
+              Authorization: "Bearer test-token",
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({
+              toPersonId: "test-person",
+              markdown: "Test",
+            }),
+          })
+        ).rejects.toThrow("timeout");
+      } finally {
+        mockFetch.mockRestore();
+      }
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Message Formatting
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("message formatting", () => {
+    it("builds markdown with title only", () => {
+      const title = "System Alert";
+      const importance = "info" as const;
+      const importanceEmoji = { info: "ℹ️", warning: "⚠️", critical: "🚨" };
+
+      const markdown = `${importanceEmoji[importance]} **${title}**`;
+
+      expect(markdown).toBe("ℹ️ **System Alert**");
+    });
+
+    it("builds markdown with title and body", () => {
+      const title = "System Alert";
+      const body = "The system has recovered.";
+      const importance = "info" as const;
+      const importanceEmoji = { info: "ℹ️", warning: "⚠️", critical: "🚨" };
+
+      let markdown = `${importanceEmoji[importance]} **${title}**`;
+      markdown += `\n\n${body}`;
+
+      expect(markdown).toBe("ℹ️ **System Alert**\n\nThe system has recovered.");
+    });
+
+    it("builds markdown with action link", () => {
+      const title = "Incident Created";
+      const body = "A new incident has been reported.";
+      const action = {
+        label: "View Incident",
+        url: "https://example.com/incident/123",
+      };
+      const importance = "critical" as const;
+      const importanceEmoji = { info: "ℹ️", warning: "⚠️", critical: "🚨" };
+
+      let markdown = `${importanceEmoji[importance]} **${title}**`;
+      markdown += `\n\n${body}`;
+      markdown += `\n\n[${action.label}](${action.url})`;
+
+      expect(markdown).toContain("🚨 **Incident Created**");
+      expect(markdown).toContain("A new incident has been reported.");
+      expect(markdown).toContain(
+        "[View Incident](https://example.com/incident/123)"
+      );
+    });
+  });
+});

package/src/index.ts

@@ -0,0 +1,206 @@
+import { z } from "zod";
+import {
+  createBackendPlugin,
+  configString,
+  Versioned,
+  type NotificationStrategy,
+  type NotificationSendContext,
+  type NotificationDeliveryResult,
+} from "@checkstack/backend-api";
+import { notificationStrategyExtensionPoint } from "@checkstack/notification-backend";
+import { pluginMetadata } from "./plugin-metadata";
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Configuration Schemas
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+/**
+ * Admin configuration for Webex strategy.
+ * Bot tokens are long-lived (100+ years) so no refresh is needed.
+ */
+const webexConfigSchemaV1 = z.object({
+  botToken: configString({ "x-secret": true }).describe(
+    "Webex Bot Access Token from developer.webex.com"
+  ),
+});
+
+type WebexConfig = z.infer<typeof webexConfigSchemaV1>;
+
+/**
+ * User configuration for Webex - users provide their Person ID for direct messages.
+ */
+const webexUserConfigSchema = z.object({
+  personId: z.string().min(1).describe("Your Webex Person ID"),
+});
+
+type WebexUserConfig = z.infer<typeof webexUserConfigSchema>;
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Instructions
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const adminInstructions = `
+## Create a Webex Bot
+
+1. Go to [developer.webex.com](https://developer.webex.com/) and sign in
+2. Navigate to **My Webex Apps** → **Create a New App** → **Create a Bot**
+3. Fill in the bot details:
+   - **Bot Name**: Your notification bot name (e.g., "Checkstack Alerts")
+   - **Bot Username**: A unique username
+   - **Icon**: Upload an icon or use default
+   - **Description**: Brief description of the bot
+4. Click **Create Bot**
+5. Copy the **Bot Access Token** — this is shown only once!
+
+> **Important**: Bot tokens are long-lived (100+ years) but can only be viewed once. Store it securely.
+`.trim();
+
+const userInstructions = `
+## Get Your Webex Person ID
+
+1. Open your Webex app and start a chat with your organization's notification bot
+2. Send any message to the bot (this creates the 1:1 space)
+3. To find your Person ID, use one of these methods:
+
+**Method 1: Via Webex Developer Portal**
+- Go to [developer.webex.com/docs/api/v1/people/get-my-own-details](https://developer.webex.com/docs/api/v1/people/get-my-own-details)
+- Click "Run" — your Person ID is in the response
+
+**Method 2: Ask your admin**
+- Your Webex admin can look up your Person ID via the admin console
+
+4. Enter your Person ID above and save
+
+> **Note**: You must have messaged the bot at least once before notifications can be sent.
+`.trim();
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Webex Strategy Implementation
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+const WEBEX_API_BASE = "https://webexapis.com/v1";
+
+/**
+ * Webex notification strategy.
+ * Sends notifications as direct messages via the Webex Messages API.
+ */
+const webexStrategy: NotificationStrategy<WebexConfig, WebexUserConfig> = {
+  id: "webex",
+  displayName: "Webex",
+  description: "Send notifications via Webex direct messages",
+  icon: "MessageSquare",
+
+  config: new Versioned({
+    version: 1,
+    schema: webexConfigSchemaV1,
+  }),
+
+  // User-config resolution - users enter their Person ID
+  contactResolution: { type: "user-config", field: "personId" },
+
+  userConfig: new Versioned({
+    version: 1,
+    schema: webexUserConfigSchema,
+  }),
+
+  adminInstructions,
+  userInstructions,
+
+  async send(
+    context: NotificationSendContext<WebexConfig, WebexUserConfig>
+  ): Promise<NotificationDeliveryResult> {
+    const { userConfig, notification, strategyConfig } = context;
+
+    if (!strategyConfig.botToken) {
+      return {
+        success: false,
+        error: "Webex bot token not configured",
+      };
+    }
+
+    if (!userConfig?.personId) {
+      return {
+        success: false,
+        error: "User has not configured their Webex Person ID",
+      };
+    }
+
+    try {
+      // Build message with markdown formatting
+      const importanceEmoji = {
+        info: "ℹ️",
+        warning: "⚠️",
+        critical: "🚨",
+      };
+
+      let markdown = `${importanceEmoji[notification.importance]} **${
+        notification.title
+      }**`;
+
+      if (notification.body) {
+        markdown += `\n\n${notification.body}`;
+      }
+
+      if (notification.action?.url) {
+        markdown += `\n\n[${notification.action.label}](${notification.action.url})`;
+      }
+
+      // Send message via Webex API
+      const response = await fetch(`${WEBEX_API_BASE}/messages`, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${strategyConfig.botToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          toPersonId: userConfig.personId,
+          markdown,
+        }),
+        signal: AbortSignal.timeout(10_000),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        return {
+          success: false,
+          error: `Webex API error (${response.status}): ${errorText.slice(
+            0,
+            200
+          )}`,
+        };
+      }
+
+      const result = (await response.json()) as { id?: string };
+
+      return {
+        success: true,
+        externalId: result.id,
+      };
+    } catch (error) {
+      const message =
+        error instanceof Error ? error.message : "Unknown Webex API error";
+      return {
+        success: false,
+        error: `Failed to send Webex message: ${message}`,
+      };
+    }
+  },
+};
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// Plugin Definition
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+export default createBackendPlugin({
+  metadata: pluginMetadata,
+
+  register(env) {
+    // Get the notification strategy extension point
+    const extensionPoint = env.getExtensionPoint(
+      notificationStrategyExtensionPoint
+    );
+
+    // Register the Webex strategy with our plugin metadata
+    extensionPoint.addStrategy(webexStrategy, pluginMetadata);
+  },
+});

package/src/plugin-metadata.ts

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

package/tsconfig.json

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