@checkstack/maintenance-backend 0.5.17 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @checkstack/maintenance-backend
 
+## 0.6.0
+
+### Minor Changes
+
+- 298bf42: ### Notification System Optimizations
+
+  **System context in notifications**: All notification senders (healthcheck, incident, maintenance, dependency) now include the affected system name in the notification title and body. Users can immediately identify which system is affected without clicking through to the detail page.
+
+  **Upstream notification deduplication**: When an upstream dependency goes down affecting multiple downstream systems, the dependency notification sidecar now sends **one personalized notification per user** instead of one notification per affected system. Each user's notification lists only the systems they are subscribed to, with a link to the upstream root cause system. This prevents notification floods for users subscribed to groups containing many dependent systems.
+
+  **New catalog endpoint**: Added `getSystemGroupIds` S2S RPC endpoint on the catalog to resolve which catalog groups contain a given system, used by the dependency plugin for efficient subscriber resolution during batched notification dispatch.
+
+### Patch Changes
+
+- Updated dependencies [298bf42]
+  - @checkstack/catalog-common@1.5.0
+
 ## 0.5.17
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/maintenance-backend",
-  "version": "0.5.17",
+  "version": "0.6.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -16,8 +16,8 @@
     "@checkstack/backend-api": "0.12.0",
     "@checkstack/maintenance-common": "0.4.9",
     "@checkstack/notification-common": "0.2.8",
-    "@checkstack/catalog-common": "1.4.0",
-    "@checkstack/auth-common": "0.6.1",
+    "@checkstack/catalog-common": "1.4.1",
+    "@checkstack/auth-common": "0.6.2",
     "@checkstack/command-backend": "0.1.19",
     "@checkstack/signal-common": "0.1.9",
     "@checkstack/integration-backend": "0.1.19",

package/src/notifications.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { notifyAffectedSystems } from "./notifications";
+
+// Mock catalog client
+function createMockCatalogClient() {
+  return {
+    notifySystemSubscribers: mock(() => Promise.resolve()),
+  };
+}
+
+// Mock logger
+function createMockLogger() {
+  return {
+    warn: mock(() => {}),
+    error: mock(() => {}),
+    info: mock(() => {}),
+    debug: mock(() => {}),
+  };
+}
+
+describe("notifyAffectedSystems (maintenance)", () => {
+  let mockCatalogClient: ReturnType<typeof createMockCatalogClient>;
+  let mockLogger: ReturnType<typeof createMockLogger>;
+
+  beforeEach(() => {
+    mockCatalogClient = createMockCatalogClient();
+    mockLogger = createMockLogger();
+  });
+
+  describe("system name inclusion", () => {
+    it("should include system name in title when systemNames map is provided", async () => {
+      const systemNames = new Map([
+        ["sys-1", "Production Database"],
+      ]);
+
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        logger: mockLogger as never,
+        maintenanceId: "maint-1",
+        maintenanceTitle: "Scheduled DB Upgrade",
+        systemIds: ["sys-1"],
+        systemNames,
+        action: "created",
+      });
+
+      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+        expect.objectContaining({
+          title: "Maintenance scheduled: Production Database",
+          body: expect.stringContaining("**Production Database**"),
+        }),
+      );
+    });
+
+    it("should fall back to systemId when systemNames map is not provided", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        logger: mockLogger as never,
+        maintenanceId: "maint-1",
+        maintenanceTitle: "Scheduled DB Upgrade",
+        systemIds: ["sys-1"],
+        action: "started",
+      });
+
+      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+        expect.objectContaining({
+          title: "Maintenance started: sys-1",
+          body: expect.stringContaining("**sys-1**"),
+        }),
+      );
+    });
+  });
+
+  describe("action text mapping", () => {
+    it("should use 'scheduled' for created action", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        logger: mockLogger as never,
+        maintenanceId: "maint-1",
+        maintenanceTitle: "Test",
+        systemIds: ["sys-1"],
+        action: "created",
+      });
+
+      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+        expect.objectContaining({
+          title: expect.stringContaining("scheduled"),
+        }),
+      );
+    });
+
+    it("should use 'completed' for completed action", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        logger: mockLogger as never,
+        maintenanceId: "maint-1",
+        maintenanceTitle: "Test",
+        systemIds: ["sys-1"],
+        action: "completed",
+      });
+
+      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+        expect.objectContaining({
+          title: expect.stringContaining("completed"),
+        }),
+      );
+    });
+  });
+
+  describe("importance", () => {
+    it("should always use 'info' importance", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        logger: mockLogger as never,
+        maintenanceId: "maint-1",
+        maintenanceTitle: "Test",
+        systemIds: ["sys-1"],
+        action: "started",
+      });
+
+      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+        expect.objectContaining({
+          importance: "info",
+        }),
+      );
+    });
+  });
+
+  describe("error handling", () => {
+    it("should log warning but not throw when notification fails", async () => {
+      mockCatalogClient.notifySystemSubscribers.mockRejectedValue(
+        new Error("Network error"),
+      );
+
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+        logger: mockLogger as never,
+        maintenanceId: "maint-1",
+        maintenanceTitle: "Test",
+        systemIds: ["sys-1"],
+        action: "created",
+      });
+
+      expect(mockLogger.warn).toHaveBeenCalled();
+    });
+  });
+});

package/src/notifications.ts

@@ -15,6 +15,7 @@ export async function notifyAffectedSystems(props: {
   maintenanceId: string;
   maintenanceTitle: string;
   systemIds: string[];
+  systemNames?: Map<string, string>;
   action: "created" | "updated" | "started" | "completed";
 }): Promise<void> {
   const {
@@ -23,6 +24,7 @@ export async function notifyAffectedSystems(props: {
     maintenanceId,
     maintenanceTitle,
     systemIds,
+    systemNames,
     action,
   } = props;
 
@@ -38,11 +40,14 @@ export async function notifyAffectedSystems(props: {
   });
 
   for (const systemId of systemIds) {
+    // Resolve system name from provided map, or fall back to systemId
+    const systemName = systemNames?.get(systemId) ?? systemId;
+
     try {
       await catalogClient.notifySystemSubscribers({
         systemId,
-        title: `Maintenance ${actionText}`,
-        body: `A maintenance **"${maintenanceTitle}"** has been ${actionText} for a system you're subscribed to.`,
+        title: `Maintenance ${actionText}: ${systemName}`,
+        body: `Maintenance **"${maintenanceTitle}"** has been ${actionText} for **${systemName}**.`,
         importance: "info",
         action: { label: "View Maintenance", url: maintenanceDetailPath },
         includeGroupSubscribers: true,
@@ -56,3 +61,4 @@ export async function notifyAffectedSystems(props: {
     }
   }
 }
+