@checkstack/incident-backend 0.6.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,159 @@
 # @checkstack/incident-backend
 
+## 1.0.0
+
+### Major Changes
+
+- 32d52c6: feat: notification target pattern + per-spec subscriptions
+
+  Replaces the all-or-nothing catalog system/group notification model with a
+  platform-level target pattern. Each notification-emitting plugin declares
+  _subscription specs_ against typed _target_ objects exported from the
+  target's owning plugin (catalog ships `catalogSystemTarget` and
+  `catalogGroupTarget`). Notification-backend handles every per-resource
+  group lifecycle, parent-edge inheritance, and legacy-subscription seeding
+  — plugins never author groupId helpers, lifecycle hooks, or migration
+  code again.
+
+  **Plugin-author surface area is now ~12 lines per emitter:**
+
+  ```ts
+  // <plugin>-common
+  const { defineSubscription } = createSubscriptionFactory(pluginMetadata);
+  export const fooSystemSubscription = defineSubscription({
+    localId: "system",
+    target: catalogSystemTarget,
+    display: { title: "Foo Alerts", description: "...", iconName: "Bell" },
+  });
+
+  // <plugin>-backend register()
+  env.registerSubscriptionSpecs([fooSystemSubscription]);
+  //   ^ feeds the plugin loader's dependency sorter — each spec's
+  //     target.ownerPlugin becomes an implicit init-order dep, so this
+  //     plugin automatically waits for catalog (the target owner) to
+  //     finish init + afterPluginsReady before its own runs.
+
+  // <plugin>-backend afterPluginsReady
+  await notificationClient.registerSubscriptionSpec(
+    specToRegistration(fooSystemSubscription)
+  );
+  // dispatch
+  await notificationClient.notifyForSubscription({
+    specId: fooSystemSubscription.specId,
+    resourceKeys: [systemId],
+    title,
+    body,
+    importance,
+    action,
+    collapseKey,
+    subjects,
+  });
+
+  // <plugin>-frontend
+  createNotificationSubscriptionExtension({ spec: fooSystemSubscription });
+  ```
+
+  **Migrated plugins**: anomaly, incident, maintenance, healthcheck,
+  dependency. Each lost its bespoke `notification-groups.ts`,
+  `bootstrap*NotificationGroups`, `ensure*Group`, and inheritance walk —
+  all of that is now centralized in notification-backend's
+  `subscription-engine`.
+
+  **Plugin loader change** (`@checkstack/backend-api`,
+  `@checkstack/backend`): the register-time API gains
+  `env.registerSubscriptionSpecs([...specs])`. The dependency sorter
+  walks `spec.target.ownerPlugin` for every declared spec and adds the
+  target owner as an init-order dependency of the emitting plugin. This
+  guarantees that catalog (the owner of the platform's `system` and
+  `group` targets) completes init + afterPluginsReady before any
+  emitting plugin tries to register its specs against the notification
+  service — no string-prefix heuristics, no manual `dependsOnPlugins`
+  list, no stub rows. Plugins that fail to declare their specs at
+  register time get a clear `Target type X is not registered. Did the
+emitting plugin declare this spec via env.registerSubscriptionSpecs?`
+  error from the dispatcher.
+
+  **Removed** (no backwards compat):
+
+  - `catalogClient.notifySystemSubscribers` and
+    `catalogClient.notifyManySystemSubscribers`
+  - `notificationClient.notifyUsers` and `notificationClient.notifyGroups`
+    as direct dispatch primitives — replaced by spec-bound
+    `notifyForSubscription`
+  - catalog's `bootstrapNotificationGroups` (replaced by
+    `bootstrapNotificationTargets`)
+
+  **Enforcement**: the dispatcher rejects calls referencing unregistered
+  specIds, specs owned by other plugins, or resourceKeys that haven't been
+  pushed via `upsertNotificationResource`. Display metadata for any
+  groupId is recoverable via the spec registry, so audit lists render
+  correct labels even when an emitter's frontend isn't loaded.
+
+  **Per-field anomaly mute** keeps working — it now lives inside the
+  generic SubscriptionRow's optional `SubControls` panel
+  (`AnomalyFieldMuteList`), exposed through the catalog system detail
+  page's notifications card.
+
+  The catalog system detail page renders a "Notifications" card hosting
+  `SystemNotificationSubscriptionsSlot`. The matching group surface is
+  not yet rendered — group-level subscriptions are wired end-to-end on
+  the backend; a follow-up will add the host UI.
+
+  **Migration of existing subscribers**: target types declare a
+  `legacyGroupIdTemplate`; on first registration of each spec,
+  notification-backend reads subscribers from the legacy
+  `catalog.system.<id>` / `catalog.group.<id>` groups and seeds the new
+  spec groups exactly once per (spec × resource) pair, tracked in
+  `subscription_migrations`. Anomaly stays opt-in (its target also
+  declares the template, but the user-explicit nature of the original
+  opt-in flow means the seeding produces the same set of subscribers
+  they already had).
+
+### Minor Changes
+
+- 32d52c6: Bulk notifications affecting multiple systems and collapse lifecycle events into a single card.
+
+  Notifications now carry an optional `subjects` array (the entities they affect) and an optional `collapseKey` (so related notifications collapse into one row per recipient). Incidents, maintenances, anomalies, healthchecks, and dependency-impact events route through these new fields, so an incident affecting three systems produces one in-app notification + one external send per subscriber instead of three. Lifecycle updates for the same entity (created → updated → resolved) also collapse, with an expandable "+N updates" timeline.
+
+  Subject kinds are namespaced as `<pluginId>.<localKind>` and built via type-safe helpers exported from each domain's common package (`createSystemSubject`, `incidentCollapseKey`, etc.). The frontend kind registry (`registerSubjectKind`) lets plugins bind icon + label for their kinds; unknown kinds fall back to a generic chip.
+
+  All notification strategies (SMTP, Slack, Discord, Teams, Telegram, Pushover, Gotify, Webex, Backstage) render the affected subjects natively in their format (HTML cards, Slack blocks, Discord embed fields, adaptive cards, markdown lists, etc.).
+
+### Patch Changes
+
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+  - @checkstack/integration-backend@0.1.22
+  - @checkstack/notification-common@1.0.0
+  - @checkstack/catalog-backend@1.0.0
+  - @checkstack/catalog-common@2.0.0
+  - @checkstack/incident-common@1.0.0
+  - @checkstack/backend-api@0.14.0
+  - @checkstack/auth-common@0.6.4
+  - @checkstack/cache-api@0.2.2
+  - @checkstack/command-backend@0.1.22
+  - @checkstack/cache-utils@0.2.2
+
+## 0.6.1
+
+### Patch Changes
+
+- Updated dependencies [208ad71]
+  - @checkstack/signal-common@0.2.0
+  - @checkstack/incident-common@0.5.0
+  - @checkstack/integration-common@0.3.0
+  - @checkstack/backend-api@0.13.1
+  - @checkstack/integration-backend@0.1.21
+  - @checkstack/catalog-common@1.5.3
+  - @checkstack/catalog-backend@0.7.1
+  - @checkstack/cache-api@0.2.1
+  - @checkstack/command-backend@0.1.21
+  - @checkstack/cache-utils@0.2.1
+
 ## 0.6.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/incident-backend",
-  "version": "0.6.0",
+  "version": "1.0.0",
   "type": "module",
   "main": "src/index.ts",
   "checkstack": {
@@ -13,18 +13,19 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/backend-api": "0.12.0",
-    "@checkstack/cache-api": "0.1.0",
-    "@checkstack/cache-utils": "0.1.0",
-    "@checkstack/incident-common": "0.4.8",
-    "@checkstack/catalog-common": "1.5.1",
-    "@checkstack/catalog-backend": "0.6.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",
-    "@checkstack/integration-common": "0.2.8",
-    "@checkstack/common": "0.6.5",
+    "@checkstack/backend-api": "0.13.1",
+    "@checkstack/cache-api": "0.2.1",
+    "@checkstack/cache-utils": "0.2.1",
+    "@checkstack/incident-common": "0.5.0",
+    "@checkstack/catalog-common": "1.5.3",
+    "@checkstack/catalog-backend": "0.7.1",
+    "@checkstack/notification-common": "0.3.0",
+    "@checkstack/auth-common": "0.6.3",
+    "@checkstack/command-backend": "0.1.21",
+    "@checkstack/signal-common": "0.2.0",
+    "@checkstack/integration-backend": "0.1.21",
+    "@checkstack/integration-common": "0.3.0",
+    "@checkstack/common": "0.7.0",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
     "@orpc/server": "^1.13.2"
@@ -32,9 +33,10 @@
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.4",
     "@checkstack/scripts": "0.1.2",
-    "@checkstack/test-utils-backend": "0.1.19",
+    "@checkstack/test-utils-backend": "0.1.21",
     "@checkstack/tsconfig": "0.0.5",
     "@types/bun": "^1.0.0",
+    "drizzle-kit": "^0.31.10",
     "typescript": "^5.0.0"
   }
 }

package/src/index.ts

@@ -7,9 +7,15 @@ import {
   pluginMetadata,
   incidentContract,
   incidentRoutes,
+  incidentSystemSubscription,
+  incidentGroupSubscription,
 } from "@checkstack/incident-common";
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
 import { integrationEventExtensionPoint } from "@checkstack/integration-backend";
+import {
+  NotificationApi,
+  specToRegistration,
+} from "@checkstack/notification-common";
 import { IncidentService } from "./service";
 import { createRouter } from "./router";
 import { CatalogApi } from "@checkstack/catalog-common";
@@ -60,6 +66,10 @@ export default createBackendPlugin({
   metadata: pluginMetadata,
   register(env) {
     env.registerAccessRules(incidentAccessRules);
+    env.registerSubscriptionSpecs([
+      incidentSystemSubscription,
+      incidentGroupSubscription,
+    ]);
 
     // Register hooks as integration events
     const integrationEvents = env.getExtensionPoint(
@@ -125,6 +135,7 @@ export default createBackendPlugin({
 
         const catalogClient = rpcClient.forPlugin(CatalogApi);
         const authClient = rpcClient.forPlugin(AuthApi);
+        const notificationClient = rpcClient.forPlugin(NotificationApi);
 
         const service = new IncidentService(
           database as SafeDatabase<typeof schema>,
@@ -135,6 +146,7 @@ export default createBackendPlugin({
           service,
           signalService,
           catalogClient,
+          notificationClient,
           authClient,
           logger,
           cache,
@@ -168,12 +180,24 @@ export default createBackendPlugin({
 
         logger.debug("✅ Incident Backend initialized.");
       },
-      // Phase 3: Subscribe to catalog events for cleanup
-      afterPluginsReady: async ({ database, logger, onHook }) => {
+      // Subscribe to catalog system deletion (clean up incident
+      // associations) + register subscription specs. Per-system /
+      // per-group notification group lifecycle is fully owned by
+      // notification-backend now — incident never touches it.
+      afterPluginsReady: async ({ database, logger, onHook, rpcClient }) => {
         const typedDb = database as SafeDatabase<typeof schema>;
         const service = new IncidentService(typedDb);
+        const notificationClient = rpcClient.forPlugin(NotificationApi);
+
+        await Promise.all([
+          notificationClient.registerSubscriptionSpec(
+            specToRegistration(incidentSystemSubscription),
+          ),
+          notificationClient.registerSubscriptionSpec(
+            specToRegistration(incidentGroupSubscription),
+          ),
+        ]);
 
-        // Subscribe to catalog system deletion to clean up associations
         onHook(
           catalogHooks.systemDeleted,
           async (payload) => {

package/src/notifications.test.ts

@@ -1,14 +1,21 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
 import { notifyAffectedSystems } from "./notifications";
+import { incidentCollapseKey } from "@checkstack/incident-common";
 
-// Mock catalog client
 function createMockCatalogClient() {
   return {
-    notifySystemSubscribers: mock(() => Promise.resolve()),
+    getSystemGroups: mock(() => Promise.resolve([])),
+  };
+}
+
+function createMockNotificationClient() {
+  return {
+    notifyForSubscription: mock(() =>
+      Promise.resolve({ notifiedCount: 0 }),
+    ),
   };
 }
 
-// Mock logger
 function createMockLogger() {
   return {
     warn: mock(() => {}),
@@ -20,10 +27,12 @@ function createMockLogger() {
 
 describe("notifyAffectedSystems", () => {
   let mockCatalogClient: ReturnType<typeof createMockCatalogClient>;
+  let mockNotificationClient: ReturnType<typeof createMockNotificationClient>;
   let mockLogger: ReturnType<typeof createMockLogger>;
 
   beforeEach(() => {
     mockCatalogClient = createMockCatalogClient();
+    mockNotificationClient = createMockNotificationClient();
     mockLogger = createMockLogger();
   });
 
@@ -31,15 +40,18 @@ describe("notifyAffectedSystems", () => {
     it("should use 'info' importance for resolved action regardless of severity", async () => {
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
         incidentTitle: "Test Incident",
         systemIds: ["sys-1"],
         action: "resolved",
-        severity: "critical", // Even critical severity should be info when resolved
+        severity: "critical",
       });
 
-      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledWith(
         expect.objectContaining({
           importance: "info",
         }),
@@ -49,6 +61,7 @@ describe("notifyAffectedSystems", () => {
     it("should use 'critical' importance for reopened action with critical severity", async () => {
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
         incidentTitle: "Test Incident",
@@ -57,7 +70,9 @@ describe("notifyAffectedSystems", () => {
         severity: "critical",
       });
 
-      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledWith(
         expect.objectContaining({
           importance: "critical",
         }),
@@ -67,6 +82,7 @@ describe("notifyAffectedSystems", () => {
     it("should use 'warning' importance for created action with major severity", async () => {
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
         incidentTitle: "Test Incident",
@@ -75,7 +91,9 @@ describe("notifyAffectedSystems", () => {
         severity: "major",
       });
 
-      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledWith(
         expect.objectContaining({
           importance: "warning",
         }),
@@ -85,6 +103,7 @@ describe("notifyAffectedSystems", () => {
     it("should use 'info' importance for updated action with minor severity", async () => {
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
         incidentTitle: "Test Incident",
@@ -93,7 +112,9 @@ describe("notifyAffectedSystems", () => {
         severity: "minor",
       });
 
-      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledWith(
         expect.objectContaining({
           importance: "info",
         }),
@@ -102,113 +123,161 @@ describe("notifyAffectedSystems", () => {
   });
 
   describe("action text", () => {
-    it("should use 'reported' for created action", async () => {
+    it("titles use the incident name and action verb (no per-system suffix)", async () => {
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
-        incidentTitle: "Test Incident",
+        incidentTitle: "API Outage",
         systemIds: ["sys-1"],
         action: "created",
         severity: "minor",
       });
 
-      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledWith(
         expect.objectContaining({
-          title: "Incident reported: sys-1",
+          title: "Incident reported: API Outage",
           body: expect.stringContaining("reported"),
         }),
       );
     });
 
-    it("should use 'reopened' for reopened action", async () => {
+    it("uses 'reopened' verb on reopen", async () => {
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
-        incidentTitle: "Test Incident",
+        incidentTitle: "API Outage",
         systemIds: ["sys-1"],
         action: "reopened",
         severity: "minor",
       });
 
-      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledWith(
         expect.objectContaining({
-          title: "Incident reopened: sys-1",
-          body: expect.stringContaining("reopened"),
+          title: "Incident reopened: API Outage",
         }),
       );
     });
   });
 
-  describe("system deduplication", () => {
-    it("should deduplicate system IDs", async () => {
+  describe("bulking", () => {
+    it("emits a single batched call regardless of how many affected systems", async () => {
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
         incidentTitle: "Test Incident",
-        systemIds: ["sys-1", "sys-1", "sys-2", "sys-2", "sys-1"],
+        systemIds: ["sys-1", "sys-2", "sys-3"],
         action: "created",
         severity: "minor",
       });
 
-      // Should only be called twice (for sys-1 and sys-2)
-      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledTimes(
-        2,
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledTimes(1);
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledWith(
+        expect.objectContaining({
+          resourceKeys: ["sys-1", "sys-2", "sys-3"],
+        }),
       );
     });
-  });
 
-  describe("error handling", () => {
-    it("should log warning but not throw when notification fails", async () => {
-      mockCatalogClient.notifySystemSubscribers.mockRejectedValue(
-        new Error("Network error"),
+    it("deduplicates repeated system ids in the input list", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "Test Incident",
+        systemIds: ["sys-1", "sys-1", "sys-2", "sys-2", "sys-1"],
+        action: "created",
+        severity: "minor",
+      });
+
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledTimes(1);
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledWith(
+        expect.objectContaining({
+          resourceKeys: ["sys-1", "sys-2"],
+        }),
       );
+    });
 
-      // Should not throw
+    it("skips the call when there are no affected systems", async () => {
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
         incidentTitle: "Test Incident",
-        systemIds: ["sys-1"],
+        systemIds: [],
         action: "created",
         severity: "minor",
       });
 
-      expect(mockLogger.warn).toHaveBeenCalled();
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).not.toHaveBeenCalled();
     });
   });
 
-  describe("system name inclusion", () => {
-    it("should include system name in title and body when systemNames map is provided", async () => {
+  describe("subjects + collapseKey", () => {
+    it("includes one subject per affected system with name + url", async () => {
       const systemNames = new Map([
         ["sys-1", "Production Database"],
+        ["sys-2", "Cache Layer"],
       ]);
 
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
         incidentTitle: "DB Outage",
-        systemIds: ["sys-1"],
+        systemIds: ["sys-1", "sys-2"],
         systemNames,
         action: "created",
         severity: "critical",
       });
 
-      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [
+          { subjects?: Array<Record<string, unknown>> },
+        ]
+      )[0];
+      expect(call?.subjects).toEqual([
         expect.objectContaining({
-          title: "Incident reported: Production Database",
-          body: expect.stringContaining("**Production Database**"),
+          kind: "catalog.system", // produced by createSystemSubject
+          id: "sys-1",
+          name: "Production Database",
+          url: expect.stringContaining("sys-1"),
         }),
-      );
+        expect.objectContaining({
+          kind: "catalog.system", // produced by createSystemSubject
+          id: "sys-2",
+          name: "Cache Layer",
+        }),
+      ]);
     });
 
-    it("should fall back to systemId when systemNames map is not provided", async () => {
+    it("falls back to systemId for the subject name when no map is provided", async () => {
       await notifyAffectedSystems({
         catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
         logger: mockLogger as never,
         incidentId: "inc-1",
         incidentTitle: "Test Incident",
@@ -217,13 +286,55 @@ describe("notifyAffectedSystems", () => {
         severity: "minor",
       });
 
-      expect(mockCatalogClient.notifySystemSubscribers).toHaveBeenCalledWith(
+      const call = (
+        mockNotificationClient.notifyForSubscription.mock
+          .calls[0] as unknown as [
+          { subjects?: Array<Record<string, unknown>> },
+        ]
+      )[0];
+      expect(call?.subjects?.[0]?.name).toBe("sys-1");
+    });
+
+    it("uses a stable collapseKey derived from the incident id", async () => {
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-42",
+        incidentTitle: "Test Incident",
+        systemIds: ["sys-1"],
+        action: "created",
+        severity: "minor",
+      });
+
+      expect(
+        mockNotificationClient.notifyForSubscription,
+      ).toHaveBeenCalledWith(
         expect.objectContaining({
-          title: "Incident resolved: sys-1",
-          body: expect.stringContaining("**sys-1**"),
+          collapseKey: incidentCollapseKey("inc-42"),
         }),
       );
     });
   });
-});
 
+  describe("error handling", () => {
+    it("logs a warning but does not throw when the notify call fails", async () => {
+      mockNotificationClient.notifyForSubscription.mockRejectedValue(
+        new Error("Network error"),
+      );
+
+      await notifyAffectedSystems({
+        catalogClient: mockCatalogClient as never,
+      notificationClient: mockNotificationClient as never,
+        logger: mockLogger as never,
+        incidentId: "inc-1",
+        incidentTitle: "Test Incident",
+        systemIds: ["sys-1"],
+        action: "created",
+        severity: "minor",
+      });
+
+      expect(mockLogger.warn).toHaveBeenCalled();
+    });
+  });
+});

package/src/notifications.ts

@@ -1,40 +1,27 @@
-import { CatalogApi } from "@checkstack/catalog-common";
+import {
+  CatalogApi,
+  catalogRoutes,
+  createSystemSubject,
+} from "@checkstack/catalog-common";
 import type { Logger } from "@checkstack/backend-api";
 import type { InferClient } from "@checkstack/common";
 import { resolveRoute } from "@checkstack/common";
-import { incidentRoutes } from "@checkstack/incident-common";
+import type { NotificationApi } from "@checkstack/notification-common";
+import {
+  incidentRoutes,
+  incidentCollapseKey,
+  incidentSystemSubscription,
+} from "@checkstack/incident-common";
 
 /**
- * Determines notification importance based on action and severity.
- * Resolved actions are always "info" (good news).
- * Other actions derive importance from severity.
- */
-function getImportance(
-  action: "created" | "updated" | "resolved" | "reopened",
-  severity: string,
-): "info" | "warning" | "critical" {
-  // Resolved is always good news
-  if (action === "resolved") {
-    return "info";
-  }
-
-  // For other actions, derive from severity
-  if (severity === "critical") {
-    return "critical";
-  }
-  if (severity === "major") {
-    return "warning";
-  }
-  return "info";
-}
-
-/**
- * Helper to notify subscribers of affected systems about an incident event.
- * Each system triggers a separate notification call, but within each call
- * the subscribers are deduplicated (system + its groups).
+ * Send a single notification to every subscriber across the affected
+ * systems and their parent catalog groups. Inheritance and dedup are
+ * handled inside notification-backend — incident only supplies the
+ * resource keys (system ids) and the payload.
  */
 export async function notifyAffectedSystems(props: {
   catalogClient: InferClient<typeof CatalogApi>;
+  notificationClient: InferClient<typeof NotificationApi>;
   logger: Logger;
   incidentId: string;
   incidentTitle: string;
@@ -44,7 +31,7 @@ export async function notifyAffectedSystems(props: {
   severity: string;
 }): Promise<void> {
   const {
-    catalogClient,
+    notificationClient,
     logger,
     incidentId,
     incidentTitle,
@@ -53,6 +40,10 @@ export async function notifyAffectedSystems(props: {
     action,
     severity,
   } = props;
+  void props.catalogClient;
+
+  const uniqueSystemIds = [...new Set(systemIds)];
+  if (uniqueSystemIds.length === 0) return;
 
   const actionText = {
     created: "reported",
@@ -62,34 +53,42 @@ export async function notifyAffectedSystems(props: {
   }[action];
 
   const importance = getImportance(action, severity);
-
   const incidentDetailPath = resolveRoute(incidentRoutes.routes.detail, {
     incidentId,
   });
+  const subjects = uniqueSystemIds.map((systemId) =>
+    createSystemSubject({
+      id: systemId,
+      name: systemNames?.get(systemId) ?? systemId,
+      url: resolveRoute(catalogRoutes.routes.systemDetail, { systemId }),
+    }),
+  );
 
-  // Deduplicate: collect unique system IDs
-  const uniqueSystemIds = [...new Set(systemIds)];
-
-  for (const systemId of uniqueSystemIds) {
-    // Resolve system name from provided map, or fall back to systemId
-    const systemName = systemNames?.get(systemId) ?? systemId;
-
-    try {
-      await catalogClient.notifySystemSubscribers({
-        systemId,
-        title: `Incident ${actionText}: ${systemName}`,
-        body: `Incident **"${incidentTitle}"** has been ${actionText} affecting **${systemName}**.`,
-        importance,
-        action: { label: "View Incident", url: incidentDetailPath },
-        includeGroupSubscribers: true,
-      });
-    } catch (error) {
-      // Log but don't fail the operation - notifications are best-effort
-      logger.warn(
-        `Failed to notify subscribers for system ${systemId}:`,
-        error,
-      );
-    }
+  try {
+    await notificationClient.notifyForSubscription({
+      specId: incidentSystemSubscription.specId,
+      resourceKeys: uniqueSystemIds,
+      title: `Incident ${actionText}: ${incidentTitle}`,
+      body: `Incident **"${incidentTitle}"** has been ${actionText}.`,
+      importance,
+      action: { label: "View Incident", url: incidentDetailPath },
+      collapseKey: incidentCollapseKey(incidentId),
+      subjects,
+    });
+  } catch (error) {
+    logger.warn(
+      `Failed to notify subscribers for incident ${incidentId}:`,
+      error,
+    );
   }
 }
 
+function getImportance(
+  action: "created" | "updated" | "resolved" | "reopened",
+  severity: string,
+): "info" | "warning" | "critical" {
+  if (action === "resolved") return "info";
+  if (severity === "critical") return "critical";
+  if (severity === "major") return "warning";
+  return "info";
+}

package/src/router.ts

@@ -22,6 +22,9 @@ export function createRouter(
   service: IncidentService,
   signalService: SignalService,
   catalogClient: InferClient<typeof CatalogApi>,
+  notificationClient: InferClient<
+    typeof import("@checkstack/notification-common").NotificationApi
+  >,
   authClient: InferClient<typeof AuthApi>,
   logger: Logger,
   cache: IncidentCache,
@@ -175,6 +178,7 @@ export function createRouter(
       const systemNames = await resolveSystemNames(result.systemIds);
       await notifyAffectedSystems({
         catalogClient,
+        notificationClient,
         logger,
         incidentId: result.id,
         incidentTitle: result.title,
@@ -219,6 +223,7 @@ export function createRouter(
       const systemNames = await resolveSystemNames(result.systemIds);
       await notifyAffectedSystems({
         catalogClient,
+        notificationClient,
         logger,
         incidentId: result.id,
         incidentTitle: result.title,
@@ -296,6 +301,7 @@ export function createRouter(
           const systemNames = await resolveSystemNames(incident.systemIds);
           await notifyAffectedSystems({
             catalogClient,
+            notificationClient,
             logger,
             incidentId: input.incidentId,
             incidentTitle: incident.title,
@@ -347,6 +353,7 @@ export function createRouter(
       const systemNames = await resolveSystemNames(result.systemIds);
       await notifyAffectedSystems({
         catalogClient,
+        notificationClient,
         logger,
         incidentId: result.id,
         incidentTitle: result.title,