@checkstack/notification-common 0.3.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,205 @@
 # @checkstack/notification-common
 
+## 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: feat(anomaly): per-system and per-field notification mute
+
+  Anomaly notifications now flow through their own subscription group
+  (`anomaly.system.<systemId>`) instead of the shared catalog system group, so
+  users can opt out of anomaly noise without losing incident or healthcheck
+  alerts for the same system. On first deploy, existing subscribers of each
+  `catalog.system.<id>` group are seeded onto the new anomaly group so no one
+  silently stops getting alerts.
+
+  A new mute table (`anomaly_notification_mutes`) backs two granularities:
+
+  - **Per-field**: silence a single noisy metric on one system.
+  - **Per-system**: silence every anomaly for one system in one click.
+
+  The system anomaly widget now exposes a bell icon on each anomaly row plus a
+  `Mute all` toggle in the card header. Mutes are user-scoped and persist
+  across sessions.
+
+  Catalog gains a `systemCreated` hook so anomaly (and any future plugin) can
+  provision per-system state on creation rather than waiting for a restart.
+  The notification service gains a `bulkSubscribe` service-RPC used by the
+  one-time migration described above.
+
+- 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.).
+
+- 32d52c6: feat: unified notification-subscription manager dialog driven by spec registry
+
+  Replaces the bell-toggle UX (which only managed a single legacy
+  catalog group) with a modal that lists every notification type
+  registered against a target — system or group — and exposes both
+  per-type toggles and a bulk "Subscribe to all / Unsubscribe from all"
+  action. Both surfaces (system detail page header bell, dashboard group
+  header bell) now open the same `NotificationSubscriptionsManager`
+  component.
+
+  **Key change vs. the prior slot-based approach**: rows are now driven
+  by `notificationClient.listSubscriptionSpecs` — the backend's spec
+  registry is the single source of truth. Previously, a row only
+  appeared if a frontend plugin had remembered to register a
+  `createNotificationSubscriptionExtension`; this caused silent drift
+  (healthcheck and dependency registered backend specs without frontend
+  extensions, so the dialog counted them but never rendered rows). Now,
+  every spec the platform knows about renders a row using the spec's
+  `display` metadata (title, description, iconName resolved via
+  `DynamicIcon`).
+
+  **Sub-controls registry** (`@checkstack/notification-frontend`):
+  plugins that want sub-granularity (anomaly's per-field mute list,
+  future severity / channel filters) call
+  `registerSubscriptionSubControls(spec, Component)` at module load —
+  the manager looks the component up by `specId` when expanding a row.
+
+  **Removed (no compat)**:
+
+  - `createNotificationSubscriptionExtension` (replaced by the
+    spec-driven manager + the SubControls registry)
+  - `target.slot` field on `NotificationTarget` and the
+    `NotificationTargetInput.slot` parameter on
+    `defineNotificationTarget`
+  - `SystemNotificationSubscriptionsSlot` and
+    `GroupNotificationSubscriptionsSlot` from `@checkstack/catalog-common`
+  - `SystemNotificationsCard` from the system detail page's main column
+  - `SubscribeButton` wiring on dashboard group cards and the system
+    detail page header
+
+  **Migrated frontends**: anomaly (now registers `AnomalyFieldMuteList`
+  via the SubControls registry), incident, maintenance — all dropped
+  their `createNotificationSubscriptionExtension` calls. healthcheck and
+  dependency now show up automatically via the spec registry — no
+  frontend changes needed for them to render.
+
+  The trigger button reflects aggregate state — filled bell when at
+  least one spec is subscribed for the resource, ghost bell when none.
+
+### Patch Changes
+
+- 32d52c6: Fix and improve password reset flow + email branding:
+
+  - **Fix**: password reset emails were failing with "Malformed password reset URL: missing token parameter". Better-auth puts the reset token in the URL path (`/reset-password/{token}`), not as a `?token=` query param, so the previous URL-parsing logic always failed. Now uses the `token` argument better-auth passes to `sendResetPassword` directly.
+  - **UX**: the reset password page now validates the token on load via a new anonymous `validateResetToken` endpoint, so users see "Invalid Link" / "Link Expired" before typing a password rather than after submitting. Tokens are 24-char nanoid-style values (~143 bits of entropy), so exposing validity does not enable enumeration.
+  - **Fix**: transactional notifications were hardcoded to `importance: "critical"`, causing password reset emails to display a misleading "CRITICAL" badge. The `sendTransactional` contract now accepts an optional `importance` field that defaults to `"info"`.
+  - **Branding**: redesigned the email layout (`wrapInEmailLayout`) with a Checkstack-style engineering aesthetic — dark header with grid pattern, monospace importance badge, hardened CTA button (Outlook VML fallback + explicit text color), and force-light color scheme to prevent client auto-inversion from breaking text legibility.
+
 ## 0.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/notification-common",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "type": "module",
   "exports": {
     ".": {
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@checkstack/common": "0.7.0",
-    "@checkstack/signal-common": "0.1.10",
+    "@checkstack/signal-common": "0.2.0",
     "@orpc/contract": "^1.13.14",
     "zod": "^4.0.0"
   },

package/src/builders.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from "bun:test";
+import {
+  createSubjectKindBuilder,
+  createCollapseKeyBuilder,
+} from "./builders";
+import { NotificationSubjectSchema } from "./schemas";
+
+describe("createSubjectKindBuilder", () => {
+  const pluginMetadata = { pluginId: "catalog" };
+  const createSystemSubject = createSubjectKindBuilder(
+    pluginMetadata,
+    "system",
+  );
+
+  it("namespaces the kind as '<pluginId>.<localKind>'", () => {
+    const subject = createSystemSubject({ id: "sys-1", name: "Test" });
+    expect(subject.kind).toBe("catalog.system");
+  });
+
+  it("preserves all entity fields", () => {
+    const subject = createSystemSubject({
+      id: "sys-1",
+      name: "Test",
+      url: "/systems/sys-1",
+      status: "unhealthy",
+    });
+    expect(subject).toEqual({
+      kind: "catalog.system",
+      id: "sys-1",
+      name: "Test",
+      url: "/systems/sys-1",
+      status: "unhealthy",
+    });
+  });
+
+  it("produces values that pass NotificationSubjectSchema validation", () => {
+    const subject = createSystemSubject({ id: "sys-1", name: "Test" });
+    expect(() => NotificationSubjectSchema.parse(subject)).not.toThrow();
+  });
+
+  it("each builder is independent across plugins and local kinds", () => {
+    const incidentSubject = createSubjectKindBuilder(
+      { pluginId: "incident" },
+      "incident",
+    )({ id: "inc-1", name: "Outage" });
+    const groupSubject = createSubjectKindBuilder(
+      pluginMetadata,
+      "group",
+    )({ id: "grp-1", name: "Team" });
+
+    expect(incidentSubject.kind).toBe("incident.incident");
+    expect(groupSubject.kind).toBe("catalog.group");
+  });
+});
+
+describe("createCollapseKeyBuilder", () => {
+  const pluginMetadata = { pluginId: "incident" };
+  const incidentCollapseKey = createCollapseKeyBuilder(
+    pluginMetadata,
+    "incident",
+  );
+
+  it("returns '<pluginId>.<localKind>.<entityId>' for single ids", () => {
+    expect(incidentCollapseKey("inc-1")).toBe("incident.incident.inc-1");
+  });
+
+  it("joins multiple id components with dots", () => {
+    const anomalyKey = createCollapseKeyBuilder(
+      { pluginId: "anomaly" },
+      "anomaly",
+    );
+    expect(anomalyKey("sys-1", "cpu.usage")).toBe(
+      "anomaly.anomaly.sys-1.cpu.usage",
+    );
+  });
+
+  it("uses the same prefix for every call", () => {
+    const a = incidentCollapseKey("inc-1");
+    const b = incidentCollapseKey("inc-2");
+    expect(a.split(".").slice(0, 2)).toEqual(b.split(".").slice(0, 2));
+  });
+});

package/src/builders.ts

@@ -0,0 +1,86 @@
+import type { NotificationSubject } from "./schemas";
+
+/**
+ * Plugin-metadata shape relied on by the builders below. Mirrors the
+ * `pluginId` field on the `definePluginMetadata` return type without
+ * importing the rest of `@checkstack/common` into this file.
+ */
+interface PluginMetadataLike {
+  pluginId: string;
+}
+
+/**
+ * Returns a typed builder that produces `NotificationSubject` instances for
+ * a specific plugin's local entity kind. The resulting `kind` string is
+ * always namespaced as `<pluginId>.<localKind>`, so callers can never
+ * forget the prefix and the namespace updates automatically if a plugin's
+ * id changes.
+ *
+ * Example:
+ * ```ts
+ * import { createSubjectKindBuilder } from "@checkstack/notification-common";
+ * import { pluginMetadata } from "./plugin-metadata";
+ *
+ * export const createSystemSubject = createSubjectKindBuilder(
+ *   pluginMetadata,
+ *   "system",
+ * );
+ *
+ * // Elsewhere:
+ * const subject = createSystemSubject({
+ *   id: "sys-1",
+ *   name: "Production DB",
+ *   url: "/system/sys-1",
+ * });
+ * // -> { kind: "catalog.system", id: "sys-1", name: "Production DB", url: ... }
+ * ```
+ */
+export function createSubjectKindBuilder(
+  pluginMetadata: PluginMetadataLike,
+  localKind: string,
+): (props: {
+  id: string;
+  name: string;
+  url?: string;
+  status?: NotificationSubject["status"];
+}) => NotificationSubject {
+  const kind = `${pluginMetadata.pluginId}.${localKind}`;
+  return (props) => ({
+    kind,
+    id: props.id,
+    name: props.name,
+    url: props.url,
+    status: props.status,
+  });
+}
+
+/**
+ * Returns a builder that produces collapse keys for a specific plugin's
+ * local entity kind. Output is `<pluginId>.<localKind>.<entityId>`, the
+ * convention used by the frontend to collapse related notifications into a
+ * single card.
+ *
+ * Example:
+ * ```ts
+ * import { createCollapseKeyBuilder } from "@checkstack/notification-common";
+ * import { pluginMetadata } from "./plugin-metadata";
+ *
+ * export const incidentCollapseKey = createCollapseKeyBuilder(
+ *   pluginMetadata,
+ *   "incident",
+ * );
+ *
+ * // Elsewhere:
+ * incidentCollapseKey("inc-42"); // -> "incident.incident.inc-42"
+ * ```
+ *
+ * The variadic suffix lets you scope keys further when the entity isn't a
+ * single id (e.g., `(systemId, fieldPath)` for an anomaly).
+ */
+export function createCollapseKeyBuilder(
+  pluginMetadata: PluginMetadataLike,
+  localKind: string,
+): (...entityIds: [string, ...string[]]) => string {
+  const prefix = `${pluginMetadata.pluginId}.${localKind}`;
+  return (...entityIds) => `${prefix}.${entityIds.join(".")}`;
+}

package/src/index.ts

@@ -3,4 +3,7 @@ export * from "./access";
 export * from "./rpc-contract";
 export * from "./signals";
 export * from "./plugin-metadata";
+export * from "./builders";
+export * from "./targets";
+export * from "./subscriptions";
 export { notificationRoutes } from "./routes";

package/src/rpc-contract.ts

@@ -8,8 +8,64 @@ import {
   EnrichedSubscriptionSchema,
   RetentionSettingsSchema,
   PaginationInputSchema,
+  NotificationSubjectSchema,
 } from "./schemas";
 
+// Shared input fragments for the notify* procedures.
+const NotificationActionInput = z
+  .object({
+    label: z.string(),
+    url: z.string(),
+  })
+  .optional();
+const NotificationCollapseKeyInput = z
+  .string()
+  .min(1)
+  .optional()
+  .describe(
+    "Optional collapse key. Notifications with the same (userId, collapseKey) collapse into one card on the frontend. Convention: '<pluginId>.<entityKind>.<entityId>'.",
+  );
+const NotificationSubjectsInput = z
+  .array(NotificationSubjectSchema)
+  .min(1)
+  .describe(
+    "Affected entities. Required so every dispatched notification can be cross-referenced with its subscription spec / resource. Renders as chips in-app and as native rich elements per strategy.",
+  );
+
+// ─── Subscription-spec / target contract types ───────────────────────────────
+
+const SubscriptionDisplaySchema = z.object({
+  title: z.string(),
+  description: z.string(),
+  iconName: z.string().optional(),
+});
+
+const SubscriptionSpecRecordSchema = z.object({
+  specId: z.string(),
+  ownerPlugin: z.string(),
+  localId: z.string(),
+  targetTypeId: z.string(),
+  display: SubscriptionDisplaySchema,
+});
+
+const NotificationTargetRecordSchema = z.object({
+  targetTypeId: z.string(),
+  ownerPlugin: z.string(),
+  resourceKind: z.string(),
+  parentTargetTypeId: z.string().optional(),
+  legacyGroupIdTemplate: z
+    .string()
+    .optional()
+    .describe(
+      "Template like 'catalog.system.{resourceKey}'. Backend substitutes {resourceKey} once per (spec × resource) to seed initial subscribers.",
+    ),
+});
+
+const NotificationResourceSchema = z.object({
+  resourceKey: z.string(),
+  displayLabel: z.string(),
+});
+
 // Notification RPC Contract
 export const notificationContract = {
   // ==========================================================================
@@ -95,6 +151,22 @@ export const notificationContract = {
     .input(z.object({ groupId: z.string() }))
     .output(z.void()),
 
+  /**
+   * Bulk subscription-status lookup for the current user. Used by the
+   * generic `<SubscriptionRow>` component when several specs from
+   * different plugins render against the same resource — each spec's row
+   * needs to know "am I subscribed to this groupId?" but doing N
+   * roundtrips would be wasteful. Pass every candidate groupId in one
+   * call and receive a map back.
+   */
+  getMySubscriptionStatus: proc({
+    operationType: "query",
+    userType: "user",
+    access: [],
+  })
+    .input(z.object({ groupIds: z.array(z.string()) }))
+    .output(z.record(z.string(), z.boolean())),
+
   // ==========================================================================
   // ADMIN SETTINGS ENDPOINTS (userType: "user" with admin access)
   // ==========================================================================
@@ -179,49 +251,195 @@ export const notificationContract = {
     )
     .output(z.object({ userIds: z.array(z.string()) })),
 
-  // Send notifications to a list of users (deduplicated by caller)
-  notifyUsers: proc({
+  /**
+   * Subscribe a batch of users to a group in one call. Used by plugins
+   * during bootstrap/migration when establishing default subscribers for
+   * a newly-introduced group (e.g. mirroring existing catalog system
+   * subscribers onto a derived anomaly group). Idempotent.
+   */
+  bulkSubscribe: proc({
     operationType: "mutation",
     userType: "service",
     access: [],
   })
     .input(
       z.object({
+        groupId: z.string().describe("Full namespaced group ID"),
         userIds: z.array(z.string()),
-        title: z.string(),
-        body: z.string().describe("Notification body (supports markdown)"),
-        importance: z.enum(["info", "warning", "critical"]).optional(),
-        action: z
-          .object({
-            label: z.string(),
-            url: z.string(),
-          })
-          .optional(),
       })
     )
-    .output(z.object({ notifiedCount: z.number() })),
+    .output(z.object({ subscribedCount: z.number() })),
+
+  /**
+   * Register (or update) a notification target type. Target owners call
+   * this on startup. notification-backend persists the metadata + tracks
+   * registered targets so it can route resource lifecycle events and
+   * resolve dispatch parents. Idempotent.
+   */
+  registerNotificationTarget: proc({
+    operationType: "mutation",
+    userType: "service",
+    access: [],
+  })
+    .input(NotificationTargetRecordSchema)
+    .output(z.object({ success: z.boolean() })),
+
+  /** Lists every registered target type — used by audit/settings UIs. */
+  listNotificationTargets: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [],
+  }).output(z.array(NotificationTargetRecordSchema)),
+
+  /**
+   * Push (or refresh) a single resource of a target type. Owners call
+   * this on resource creation and on rename. notification-backend
+   * provisions a notification group for every registered spec whose
+   * target matches, runs the legacy-migration seed if declared, and
+   * stores the display label for audit UIs.
+   */
+  upsertNotificationResource: proc({
+    operationType: "mutation",
+    userType: "service",
+    access: [],
+  })
+    .input(
+      z.object({
+        targetTypeId: z.string(),
+        resource: NotificationResourceSchema,
+      }),
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  /**
+   * Bulk variant. Used by target owners on platform startup to seed all
+   * existing resources at once without N round-trips.
+   */
+  upsertNotificationResources: proc({
+    operationType: "mutation",
+    userType: "service",
+    access: [],
+  })
+    .input(
+      z.object({
+        targetTypeId: z.string(),
+        resources: z.array(NotificationResourceSchema),
+      }),
+    )
+    .output(z.object({ upserted: z.number() })),
+
+  /**
+   * Remove a resource — notification-backend deletes every group derived
+   * from it across every registered spec whose target matches.
+   */
+  removeNotificationResource: proc({
+    operationType: "mutation",
+    userType: "service",
+    access: [],
+  })
+    .input(
+      z.object({
+        targetTypeId: z.string(),
+        resourceKey: z.string(),
+      }),
+    )
+    .output(z.object({ removedGroups: z.number() })),
+
+  /**
+   * Replace the full parent set for a child resource. Owners call this
+   * whenever a child's parents change — catalog calls it on
+   * `addSystemToGroup` / `removeSystemFromGroup` / system create. The
+   * dispatcher reads these edges (plus the spec→target mapping) at
+   * dispatch time to compute inherited group ids without re-walking
+   * through the owner.
+   */
+  setNotificationResourceParents: proc({
+    operationType: "mutation",
+    userType: "service",
+    access: [],
+  })
+    .input(
+      z.object({
+        childTargetTypeId: z.string(),
+        childResourceKey: z.string(),
+        parents: z.array(
+          z.object({
+            parentTargetTypeId: z.string(),
+            parentResourceKey: z.string(),
+          }),
+        ),
+      }),
+    )
+    .output(z.object({ success: z.boolean() })),
+
+  /**
+   * List known resources for a target type. Read-only convenience used
+   * by the settings page audit and by the spec-registration flow during
+   * group provisioning.
+   */
+  listNotificationResources: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [],
+  })
+    .input(z.object({ targetTypeId: z.string() }))
+    .output(z.array(NotificationResourceSchema)),
+
+  /**
+   * Register (or update) a notification subscription spec. Plugins call
+   * this on startup once per spec they own. notification-backend joins
+   * the spec against every existing resource of `targetTypeId` and
+   * provisions per-resource groups. Idempotent.
+   */
+  registerSubscriptionSpec: proc({
+    operationType: "mutation",
+    userType: "service",
+    access: [],
+  })
+    .input(SubscriptionSpecRecordSchema)
+    .output(z.object({ success: z.boolean() })),
 
-  // Notify all subscribers of multiple groups (deduplicates internally)
-  notifyGroups: proc({
+  /**
+   * Returns every currently-registered spec. Used by the settings UI to
+   * decorate subscription rows with display metadata even for plugins
+   * whose frontend isn't loaded.
+   */
+  listSubscriptionSpecs: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [],
+  }).output(z.array(SubscriptionSpecRecordSchema)),
+
+  /**
+   * The sanctioned dispatch path. Caller supplies a registered specId
+   * and one or more resource keys; notification-backend resolves
+   * primary group ids, walks the target's parent chain to compute
+   * inherited group ids (joined against the same plugin's specs whose
+   * target matches the parent target), unions subscribers, applies
+   * `excludeUserIds`, and delivers.
+   *
+   * Enforcement:
+   * - specId must exist and be owned by the calling service plugin.
+   * - resourceKeys must reference resources currently registered for
+   *   the spec's target — backend rejects unknown keys.
+   */
+  notifyForSubscription: proc({
     operationType: "mutation",
     userType: "service",
     access: [],
   })
     .input(
       z.object({
-        groupIds: z
-          .array(z.string())
-          .describe("Full namespaced group IDs to notify"),
+        specId: z.string(),
+        resourceKeys: z.array(z.string()).min(1),
+        excludeUserIds: z.array(z.string()).optional(),
         title: z.string(),
         body: z.string().describe("Notification body (supports markdown)"),
         importance: z.enum(["info", "warning", "critical"]).optional(),
-        action: z
-          .object({
-            label: z.string(),
-            url: z.string(),
-          })
-          .optional(),
-      })
+        action: NotificationActionInput,
+        collapseKey: NotificationCollapseKeyInput,
+        subjects: NotificationSubjectsInput,
+      }),
     )
     .output(z.object({ notifiedCount: z.number() })),
 
@@ -237,6 +455,10 @@ export const notificationContract = {
         notification: z.object({
           title: z.string(),
           body: z.string().describe("Notification body (supports markdown)"),
+          importance: z
+            .enum(["info", "warning", "critical"])
+            .optional()
+            .describe("Severity of the message; defaults to 'info'"),
           action: z
             .object({
               label: z.string(),

package/src/schemas.ts

@@ -11,6 +11,47 @@ export const NotificationActionSchema = z.object({
 });
 export type NotificationAction = z.infer<typeof NotificationActionSchema>;
 
+/**
+ * An entity affected by a notification (e.g., a system impacted by an
+ * incident, or a system on which a shared healthcheck is failing).
+ *
+ * Subjects render as chips in-app and as native rich elements per
+ * notification strategy (e.g., Slack section, Discord embed field, SMTP
+ * card). When a notification has no canonical parent CTA (`action` is
+ * null), the subjects' URLs are the user's only navigation path.
+ *
+ * `kind` is an open string so plugins can introduce their own subject
+ * types. To prevent clashes between plugins, kinds MUST be namespaced as
+ * `<pluginId>.<localKind>` (e.g., `catalog.system`, `incident.incident`,
+ * `healthcheck.healthcheck`). Frontend rendering metadata (icon, label)
+ * is provided via the plugin-extensible subject-kind registry in
+ * `@checkstack/notification-frontend`; unknown kinds fall back to a
+ * generic chip with the subject's `name`.
+ */
+const NAMESPACED_KIND_PATTERN = /^[a-z][a-z0-9_-]*\.[a-z][a-z0-9_-]*$/;
+
+export const NotificationSubjectSchema = z.object({
+  /**
+   * Plugin-namespaced discriminator: `<pluginId>.<localKind>`.
+   * Plugins register icon/label for their kinds in the frontend registry.
+   */
+  kind: z.string().regex(NAMESPACED_KIND_PATTERN, {
+    message: "Subject kind must be namespaced as '<pluginId>.<localKind>'",
+  }),
+  /** Stable identifier for the subject within its kind. */
+  id: z.string(),
+  /** Human-readable display name. */
+  name: z.string(),
+  /** Optional deep link to the subject. Recipients without UI access (text channels) just show the name. */
+  url: z.string().optional(),
+  /**
+   * Optional health/status hint, used to color the chip and add an icon.
+   * Strategies that cannot render color simply ignore it.
+   */
+  status: z.enum(["healthy", "unhealthy", "degraded", "unknown"]).optional(),
+});
+export type NotificationSubject = z.infer<typeof NotificationSubjectSchema>;
+
 // Core notification schema
 export const NotificationSchema = z.object({
   id: z.string().uuid(),
@@ -22,7 +63,14 @@ export const NotificationSchema = z.object({
   action: NotificationActionSchema.optional(),
   importance: ImportanceSchema,
   isRead: z.boolean(),
-  groupId: z.string().optional(),
+  /**
+   * Collapse key shared by related notifications. Frontend collapses rows
+   * with the same (userId, collapseKey) into one card with a "+N updates"
+   * badge. Examples: "incident.<id>", "healthcheck.<id>".
+   */
+  collapseKey: z.string().optional(),
+  /** Affected entities (renders as chips / native rich elements). */
+  subjects: z.array(NotificationSubjectSchema).optional(),
   createdAt: z.coerce.date(),
 });
 export type Notification = z.infer<typeof NotificationSchema>;

package/src/subscriptions.ts

@@ -0,0 +1,123 @@
+/**
+ * Cross-plugin notification-subscription pattern.
+ *
+ * A subscription spec describes one *kind* of notification a plugin
+ * offers (e.g. anomaly's "alert me about this system"). The spec
+ * references a `NotificationTarget` — a typed handle on a resource type
+ * (e.g. `catalogSystemTarget`) — and supplies display metadata. The
+ * platform handles everything else:
+ *
+ *   - notification-backend materializes one notification group per
+ *     (registered spec × known resource of the spec's target type),
+ *     keyed `<ownerPlugin>.<spec.localId>.<resourceKey>`.
+ *   - The frontend extension factory derives the slot from
+ *     `spec.target.slot` so plugin authors never re-pass it.
+ *   - At dispatch time, callers supply `(specId, resourceKeys)`;
+ *     notification-backend resolves group ids, walks the target's
+ *     `parents` chain for inheritance, and delivers.
+ *
+ * Plugin-author surface area is intentionally minimal: a `target`
+ * reference, a `localId`, and display metadata. No groupIdFor, no
+ * resourceKind (carried by the target), no slot at the registration
+ * site, no per-plugin lifecycle code.
+ */
+
+import type { NotificationTarget } from "./targets";
+
+interface PluginMetadataLike {
+  pluginId: string;
+}
+
+export interface SubscriptionDisplayMeta {
+  title: string;
+  description: string;
+  iconName?: string;
+}
+
+/**
+ * Declarative description of a subscription a plugin offers for the
+ * resources of a given target. Group ids are derived from the
+ * convention `<ownerPlugin>.<spec.localId>.<resourceKey>` — there is no
+ * escape hatch. Plugins that need an exotic group structure should
+ * register a different target type instead.
+ */
+export interface NotificationSubscriptionSpec<TResource> {
+  /** `<ownerPlugin>.<localId>` — namespaced like the target ids. */
+  readonly specId: string;
+  readonly ownerPlugin: string;
+  readonly localId: string;
+  readonly target: NotificationTarget<TResource>;
+  readonly display: SubscriptionDisplayMeta;
+}
+
+/**
+ * Derive the namespaced groupId for a given spec + resourceKey. Single
+ * source of truth — both notification-backend and dispatch callers go
+ * through this helper. Defined here in common so plugin code never
+ * computes it.
+ */
+export function subscriptionGroupId(
+  spec: { ownerPlugin: string; localId: string },
+  resourceKey: string,
+): string {
+  return `${spec.ownerPlugin}.${spec.localId}.${resourceKey}`;
+}
+
+export interface SubscriptionSpecInput<TResource> {
+  localId: string;
+  target: NotificationTarget<TResource>;
+  display: SubscriptionDisplayMeta;
+}
+
+/**
+ * Bind a plugin's id once and return a `defineSubscription` helper that
+ * stamps every spec with `<pluginId>.<localId>`. Mirrors the existing
+ * factory pattern in `builders.ts`.
+ */
+export function createSubscriptionFactory(pluginMetadata: PluginMetadataLike) {
+  const pluginId = pluginMetadata.pluginId;
+
+  function defineSubscription<TResource>(
+    input: SubscriptionSpecInput<TResource>,
+  ): NotificationSubscriptionSpec<TResource> {
+    if (input.localId.includes(".")) {
+      throw new Error(
+        `Subscription localId must not contain '.', got ${JSON.stringify(input.localId)}`,
+      );
+    }
+    return {
+      specId: `${pluginId}.${input.localId}`,
+      ownerPlugin: pluginId,
+      localId: input.localId,
+      target: input.target,
+      display: input.display,
+    };
+  }
+
+  return { defineSubscription };
+}
+
+/**
+ * Wire-format for spec registration. Includes the target type id so the
+ * backend can join known resources of that target onto the spec when
+ * provisioning groups, without re-walking type info.
+ */
+export interface RegisteredSubscriptionSpecRecord {
+  specId: string;
+  ownerPlugin: string;
+  localId: string;
+  targetTypeId: string;
+  display: SubscriptionDisplayMeta;
+}
+
+export function specToRegistration<TResource>(
+  spec: NotificationSubscriptionSpec<TResource>,
+): RegisteredSubscriptionSpecRecord {
+  return {
+    specId: spec.specId,
+    ownerPlugin: spec.ownerPlugin,
+    localId: spec.localId,
+    targetTypeId: spec.target.targetTypeId,
+    display: spec.display,
+  };
+}

package/src/targets.ts

@@ -0,0 +1,164 @@
+/**
+ * Notification target types — the platform abstraction that lets emitting
+ * plugins declare *what kind of resource* their subscriptions are about
+ * without dealing with notification-group lifecycle themselves.
+ *
+ * A target type ("system", "group", future kinds…) is owned by exactly
+ * one plugin. The owner:
+ *   1. Defines + exports the target object via `defineNotificationTarget`.
+ *   2. Tells notification-backend about every resource of this type that
+ *      exists (`upsertNotificationResource` on creation/rename,
+ *      `removeNotificationResource` on deletion).
+ *   3. Renders an extension slot on the resource's detail page so emitting
+ *      plugins can drop their subscription rows in.
+ *
+ * notification-backend does the rest:
+ *   - Materializes one notification group per (registered spec × known
+ *     resource), keyed `<emitterPluginId>.<spec.localId>.<resourceKey>`.
+ *   - Provisions/cleans up these groups automatically as resources and
+ *     specs come and go.
+ *   - At dispatch time, resolves spec + resourceKey(s) into the actual
+ *     group ids (primary + inherited via the target's `parents` chain),
+ *     unions subscribers, and delivers.
+ *
+ * Emitting plugins (anomaly, incident, maintenance, healthcheck, …) stop
+ * carrying their own per-system / per-group lifecycle — they reference
+ * a target object and supply display metadata. Convention-driven, typed,
+ * and centralized.
+ */
+
+interface PluginMetadataLike {
+  pluginId: string;
+}
+
+/**
+ * Declarative parent reference. The target owner declares what type
+ * its parent resources have ("catalogSystemTarget's parents are
+ * catalogGroupTarget"); the actual parent edges live in
+ * notification-backend's `notification_resource_parents` table and are
+ * kept in sync by the target owner via `setNotificationResourceParents`
+ * (called whenever a child's parent set changes — e.g. addSystemToGroup
+ * in catalog).
+ *
+ * No callback at dispatch time — notification-backend reads the edges
+ * from its own DB. Keeps dispatch fully server-local.
+ */
+export interface NotificationTargetParents {
+  targetTypeId: string;
+}
+
+/**
+ * Backwards-compatibility hook. If users were already subscribed to a
+ * legacy notification group (e.g. catalog's pre-pattern
+ * `catalog.system.<id>` group), the target type declares the template.
+ * notification-backend substitutes `{resourceKey}` and seeds new spec
+ * groups from the legacy group's subscribers — exactly once per
+ * (spec × resource) pair, tracked in `subscription_migrations`.
+ *
+ * Encoded as a string so the backend can run it without a callback to
+ * the target owner.
+ */
+export interface NotificationTargetLegacyMigration {
+  /** e.g. `"catalog.system.{resourceKey}"`. */
+  legacyGroupIdTemplate: string;
+}
+
+/**
+ * The on-disk representation of a known resource. Plugins owning a
+ * target type push these to notification-backend; the backend persists
+ * them so the audit/settings UI can render display labels and dispatch
+ * can iterate resources without round-tripping the owner.
+ */
+export interface NotificationTargetResourceRecord {
+  /** Stable id within the target type. */
+  resourceKey: string;
+  /** Human-friendly label shown in subscription UIs. */
+  displayLabel: string;
+}
+
+/**
+ * The full shape of a notification target. Plugins consume this via
+ * named imports and reference it from their subscription specs — never
+ * by string id.
+ */
+export interface NotificationTarget<TResource> {
+  /** `<ownerPluginId>.<localId>` — namespacing prevents collisions. */
+  readonly targetTypeId: string;
+  readonly ownerPlugin: string;
+  readonly localId: string;
+  readonly resourceKind: string;
+  /** Pulls the stable key out of a resource shape — used everywhere. */
+  keyOf(resource: TResource): string;
+  /**
+   * Pulls a human-friendly label out of a resource shape — used for
+   * upsertNotificationResource calls and the settings audit page.
+   */
+  labelOf(resource: TResource): string;
+  /** Optional parent target. Edges populated via setNotificationResourceParents. */
+  readonly parents?: NotificationTargetParents;
+  /** Optional legacy-migration declaration. Read once at startup. */
+  readonly legacy?: NotificationTargetLegacyMigration;
+}
+
+/**
+ * Plugin-bound input to `defineNotificationTarget`. The plugin author
+ * supplies a *local* id; the factory namespaces it with the plugin's
+ * id, mirroring `createSubscriptionFactory` and the existing
+ * `createCollapseKeyBuilder` pattern.
+ */
+export interface NotificationTargetInput<TResource> {
+  pluginMetadata: PluginMetadataLike;
+  localId: string;
+  resourceKind: string;
+  keyOf: NotificationTarget<TResource>["keyOf"];
+  labelOf: NotificationTarget<TResource>["labelOf"];
+  parents?: NotificationTargetParents;
+  legacy?: NotificationTargetLegacyMigration;
+}
+
+export function defineNotificationTarget<TResource>(
+  input: NotificationTargetInput<TResource>,
+): NotificationTarget<TResource> {
+  if (input.localId.includes(".")) {
+    throw new Error(
+      `Notification target localId must not contain '.', got ${JSON.stringify(input.localId)}`,
+    );
+  }
+  return {
+    targetTypeId: `${input.pluginMetadata.pluginId}.${input.localId}`,
+    ownerPlugin: input.pluginMetadata.pluginId,
+    localId: input.localId,
+    resourceKind: input.resourceKind,
+    keyOf: input.keyOf,
+    labelOf: input.labelOf,
+    parents: input.parents,
+    legacy: input.legacy,
+  };
+}
+
+/**
+ * Wire-format used when a target owner registers its target type with
+ * notification-backend on startup. Excludes the live functions
+ * (`keyOf` / `labelOf` / `parents.resolve` / `legacy.legacyGroupIdFor`)
+ * because those run in the owner's process — backend only stores
+ * metadata.
+ */
+export interface RegisteredNotificationTargetRecord {
+  targetTypeId: string;
+  ownerPlugin: string;
+  resourceKind: string;
+  parentTargetTypeId?: string;
+  legacyGroupIdTemplate?: string;
+}
+
+export function targetToRegistration<TResource>(
+  target: NotificationTarget<TResource>,
+): RegisteredNotificationTargetRecord {
+  return {
+    targetTypeId: target.targetTypeId,
+    ownerPlugin: target.ownerPlugin,
+    resourceKind: target.resourceKind,
+    parentTargetTypeId: target.parents?.targetTypeId,
+    legacyGroupIdTemplate: target.legacy?.legacyGroupIdTemplate,
+  };
+}