@checkstack/backend-api 0.13.0 → 0.14.0

package/CHANGELOG.md

@@ -1,5 +1,147 @@
 # @checkstack/backend-api
 
+## 0.14.0
+
+### 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.).
+
+- 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).
+
+### 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.
+
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+  - @checkstack/healthcheck-common@1.0.0
+  - @checkstack/cache-api@0.2.2
+  - @checkstack/queue-api@0.2.16
+
+## 0.13.1
+
+### Patch Changes
+
+- Updated dependencies [208ad71]
+  - @checkstack/signal-common@0.2.0
+  - @checkstack/healthcheck-common@0.13.0
+  - @checkstack/cache-api@0.2.1
+  - @checkstack/queue-api@0.2.15
+
 ## 0.13.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {
@@ -9,11 +9,11 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.6.5",
-    "@checkstack/healthcheck-common": "0.11.0",
-    "@checkstack/cache-api": "0.1.0",
-    "@checkstack/queue-api": "0.2.13",
-    "@checkstack/signal-common": "0.1.9",
+    "@checkstack/common": "0.7.0",
+    "@checkstack/healthcheck-common": "0.13.0",
+    "@checkstack/cache-api": "0.2.1",
+    "@checkstack/queue-api": "0.2.15",
+    "@checkstack/signal-common": "0.2.0",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
     "@orpc/openapi": "^1.13.2",

package/src/email-layout.ts

@@ -7,6 +7,18 @@
  * @module
  */
 
+/**
+ * A notification subject as rendered by the email layout. Mirrors
+ * `NotificationSubject` from `@checkstack/notification-common`.
+ */
+export interface EmailLayoutSubject {
+  kind: string;
+  id: string;
+  name: string;
+  url?: string;
+  status?: "healthy" | "unhealthy" | "degraded" | "unknown";
+}
+
 /**
  * Options for the email layout wrapper.
  */
@@ -15,20 +27,26 @@ export interface EmailLayoutOptions {
   title: string;
   /** Already-converted HTML body content */
   bodyHtml: string;
-  /** Importance level affects header/button colors */
+  /** Importance level affects the category badge color */
   importance: "info" | "warning" | "critical";
   /** Optional call-to-action button */
   action?: {
     label: string;
     url: string;
   };
+  /**
+   * Affected entities. Rendered as a card under the body, with each subject
+   * as a clickable row when `url` is present. When `action` is omitted, the
+   * subjects are the recipient's only navigation.
+   */
+  subjects?: EmailLayoutSubject[];
 
   // Admin-customizable options (via layoutConfig)
-  /** Logo URL (max ~200px wide recommended) */
+  /** Logo URL (max ~200px wide recommended). Rendered in the dark header. */
   logoUrl?: string;
-  /** Primary brand color (hex, e.g., "#3b82f6") */
+  /** Primary brand color (hex, e.g., "#7c3aed"). Used for the CTA button. */
   primaryColor?: string;
-  /** Accent color for secondary elements */
+  /** Accent color (overrides primary for the CTA button if provided). */
   accentColor?: string;
   /** Footer text */
   footerText?: string;
@@ -36,15 +54,34 @@ export interface EmailLayoutOptions {
   footerLinks?: Array<{ label: string; url: string }>;
 }
 
-// Default importance-based colors
-const IMPORTANCE_COLORS = {
-  info: "#3b82f6", // blue
-  warning: "#f59e0b", // amber
-  critical: "#ef4444", // red
+// Importance-based badge colors (rendered as monospace pills in the header)
+const IMPORTANCE_BADGES = {
+  info: { label: "INFO", bg: "#1e293b", fg: "#93c5fd" },
+  warning: { label: "WARNING", bg: "#3a2a0e", fg: "#fbbf24" },
+  critical: { label: "CRITICAL", bg: "#3a0e14", fg: "#fca5a5" },
 } as const;
 
+// Subject status dot colors. Status is optional on subjects; when absent,
+// no dot is rendered.
+const SUBJECT_STATUS_COLORS: Record<
+  NonNullable<EmailLayoutSubject["status"]>,
+  string
+> = {
+  healthy: "#22c55e",
+  degraded: "#f59e0b",
+  unhealthy: "#ef4444",
+  unknown: "#a1a1aa",
+};
+
+// Checkstack brand defaults — purple primary on near-black surfaces.
+const BRAND_PRIMARY = "#8b5cf6"; // matches --primary in dark theme
+const HEADER_BG = "#0a0a0c"; // matches --background in dark theme
+const HEADER_BORDER = "#27272a"; // matches --border in dark theme
+const HEADER_FG = "#fafafa";
+const HEADER_MUTED = "#a1a1aa";
+
 /**
- * Simple HTML escaping for security.
+ * HTML escaping for security.
  */
 function escapeHtml(text: string): string {
   return text
@@ -56,20 +93,29 @@ function escapeHtml(text: string): string {
 }
 
 /**
- * Wrap HTML content in a responsive email template.
+ * Subtle grid pattern (matches the `ambient-grid` aesthetic in the app UI).
+ * Embedded as an inline SVG data URI — supported in Apple Mail and most modern clients.
+ * Email clients that strip backgrounds (Gmail web) gracefully fall back to the solid header color.
+ */
+const GRID_PATTERN_SVG =
+  "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI0OCIgaGVpZ2h0PSI0OCI+PHBhdGggZD0iTSA0OCAwIEwgMCAwIDAgNDgiIGZpbGw9Im5vbmUiIHN0cm9rZT0iIzNmM2Y0NiIgc3Ryb2tlLXdpZHRoPSIxIiBvcGFjaXR5PSIwLjQiLz48L3N2Zz4=";
+
+/**
+ * Wrap HTML content in a Checkstack-branded responsive email template.
  *
- * This template is designed to render consistently across major
- * email clients (Gmail, Outlook, Apple Mail, etc.).
+ * The design pairs a dark "engineering" header (with optional grid pattern
+ * and monospace importance badge) with a clean light body for readability,
+ * and a purple-accented CTA button.
  *
  * @example
  * ```typescript
  * const html = wrapInEmailLayout({
  *   title: "Password Reset",
  *   bodyHtml: "<p>Click the button below to reset your password.</p>",
- *   importance: "warning",
+ *   importance: "info",
  *   action: { label: "Reset Password", url: "https://..." },
- *   primaryColor: "#10b981",
- *   footerText: "Sent by Acme Corp",
+ *   primaryColor: "#7c3aed",
+ *   footerText: "Sent by Checkstack",
  * });
  * ```
  */
@@ -79,27 +125,49 @@ export function wrapInEmailLayout(options: EmailLayoutOptions): string {
     bodyHtml,
     importance,
     action,
+    subjects,
     logoUrl,
     primaryColor,
-    footerText = "This is an automated notification.",
+    footerText = "This is an automated notification from Checkstack.",
     footerLinks = [],
   } = options;
 
-  // Use custom color or importance-based default
-  const headerColor = primaryColor ?? IMPORTANCE_COLORS[importance];
-  const buttonColor = options.accentColor ?? headerColor;
+  const buttonColor = options.accentColor ?? primaryColor ?? BRAND_PRIMARY;
+  const badge = IMPORTANCE_BADGES[importance];
+
+  const subjectsHtml =
+    subjects && subjects.length > 0
+      ? `
+              <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="margin-top: 20px; background-color: #fafafa; border: 1px solid #e4e4e7; border-radius: 8px;">
+                <tr>
+                  <td style="padding: 12px 16px;">
+                    <p class="mono" style="margin: 0 0 8px 0; color: #71717a; font-size: 10px; font-weight: 700; letter-spacing: 0.12em; text-transform: uppercase;">
+                      Affected
+                    </p>
+                    ${subjects
+                      .map((subject) => {
+                        const statusDot = subject.status
+                          ? `<span style="display:inline-block;width:8px;height:8px;border-radius:50%;background-color:${SUBJECT_STATUS_COLORS[subject.status]};margin-right:8px;vertical-align:middle;"></span>`
+                          : "";
+                        const namePart = `<span style="color:#18181b;font-size:14px;font-weight:500;vertical-align:middle;">${escapeHtml(subject.name)}</span>`;
+                        const inner = subject.url
+                          ? `<a href="${escapeHtml(subject.url)}" style="color:#18181b;text-decoration:none;">${statusDot}${namePart}</a>`
+                          : `${statusDot}${namePart}`;
+                        return `<div style="padding:6px 0;border-bottom:1px solid #e4e4e7;">${inner}</div>`;
+                      })
+                      .join("")}
+                  </td>
+                </tr>
+              </table>
+              `
+      : "";
 
-  // Build footer links HTML
   const footerLinksHtml =
     footerLinks.length > 0
       ? footerLinks
           .map(
             (link) =>
-              `<a href="${escapeHtml(
-                link.url
-              )}" style="color: #6b7280; text-decoration: underline;">${escapeHtml(
-                link.label
-              )}</a>`
+              `<a href="${escapeHtml(link.url)}" style="color: #71717a; text-decoration: underline;">${escapeHtml(link.label)}</a>`,
           )
           .join(" · ")
       : "";
@@ -110,7 +178,8 @@ export function wrapInEmailLayout(options: EmailLayoutOptions): string {
 <head>
   <meta charset="utf-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <meta name="color-scheme" content="light">
+  <!-- Force light scheme so clients don't auto-invert our intentionally dark header -->
+  <meta name="color-scheme" content="only light">
   <meta name="supported-color-schemes" content="light">
   <title>${escapeHtml(title)}</title>
   <!--[if mso]>
@@ -123,7 +192,6 @@ export function wrapInEmailLayout(options: EmailLayoutOptions): string {
   </noscript>
   <![endif]-->
   <style>
-    /* Reset styles */
     body, table, td, p, a, li, blockquote {
       -webkit-text-size-adjust: 100%;
       -ms-text-size-adjust: 100%;
@@ -144,76 +212,84 @@ export function wrapInEmailLayout(options: EmailLayoutOptions): string {
       margin: 0 !important;
       padding: 0 !important;
       width: 100% !important;
-      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+      font-family: -apple-system, BlinkMacSystemFont, 'Inter', 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
       background-color: #f4f4f5;
     }
-    /* Link styling */
-    a {
-      color: ${buttonColor};
-    }
-    /* Button styling */
-    .button {
-      display: inline-block;
-      padding: 12px 24px;
-      background-color: ${buttonColor};
-      color: #ffffff !important;
-      text-decoration: none;
-      border-radius: 6px;
-      font-weight: 600;
-      font-size: 14px;
-      line-height: 1.5;
+    .mono {
+      font-family: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
     }
+    a { color: ${buttonColor}; }
+    /* Force-light-mode hardening: prevent Outlook/Apple Mail dark-mode auto-inversion. */
+    [data-ogsc] .email-body, [data-ogsb] .email-body { color: #27272a !important; background-color: #ffffff !important; }
+    [data-ogsc] .email-card, [data-ogsb] .email-card { background-color: #ffffff !important; }
+    [data-ogsc] .email-footer, [data-ogsb] .email-footer { background-color: #fafafa !important; }
+    [data-ogsc] .button-label, [data-ogsb] .button-label { color: #ffffff !important; }
   </style>
 </head>
 <body style="margin: 0; padding: 0; background-color: #f4f4f5;">
+  <span style="display:none !important; visibility:hidden; mso-hide:all; font-size:1px; color:#f4f4f5; line-height:1px; max-height:0; max-width:0; opacity:0; overflow:hidden;">${escapeHtml(title)}</span>
   <table role="presentation" cellpadding="0" cellspacing="0" width="100%" style="background-color: #f4f4f5;">
     <tr>
-      <td align="center" style="padding: 24px 16px;">
+      <td align="center" style="padding: 32px 16px;">
         <!-- Main container -->
-        <table role="presentation" cellpadding="0" cellspacing="0" width="600" style="max-width: 600px; background-color: #ffffff; border-radius: 8px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.1);">
-          ${
-            logoUrl
-              ? `
-          <!-- Logo -->
-          <tr>
-            <td align="center" style="padding: 24px 24px 0 24px;">
-              <img src="${escapeHtml(
-                logoUrl
-              )}" alt="Logo" style="max-width: 200px; height: auto;">
-            </td>
-          </tr>
-          `
-              : ""
-          }
-          <!-- Header -->
+        <table role="presentation" cellpadding="0" cellspacing="0" width="600" class="email-card" style="max-width: 600px; background-color: #ffffff; border-radius: 12px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.06), 0 8px 24px rgba(0,0,0,0.04);">
+          <!-- Header (dark, engineering aesthetic) -->
           <tr>
-            <td style="background-color: ${headerColor}; padding: 20px 24px;">
-              <h1 style="margin: 0; color: #ffffff; font-size: 20px; font-weight: 600; line-height: 1.4;">
-                ${escapeHtml(title)}
-              </h1>
+            <td style="background-color: ${HEADER_BG}; background-image: url('${GRID_PATTERN_SVG}'); background-repeat: repeat; background-size: 48px 48px; padding: 28px 28px 24px 28px; border-bottom: 1px solid ${HEADER_BORDER};">
+              <table role="presentation" cellpadding="0" cellspacing="0" width="100%">
+                <tr>
+                  <td>
+                    ${
+                      logoUrl
+                        ? `<img src="${escapeHtml(logoUrl)}" alt="Logo" style="max-width: 160px; height: auto; display: block; margin-bottom: 14px;">`
+                        : `<div class="mono" style="color: ${HEADER_MUTED}; font-size: 11px; font-weight: 600; letter-spacing: 0.18em; text-transform: uppercase; margin-bottom: 14px;">— checkstack</div>`
+                    }
+                    <table role="presentation" cellpadding="0" cellspacing="0" style="margin-bottom: 10px;">
+                      <tr>
+                        <td class="mono" style="background-color: ${badge.bg}; color: ${badge.fg}; padding: 3px 8px; border-radius: 4px; font-size: 10px; font-weight: 700; letter-spacing: 0.12em;">
+                          ${badge.label}
+                        </td>
+                      </tr>
+                    </table>
+                    <h1 style="margin: 0; color: ${HEADER_FG}; font-size: 22px; font-weight: 600; line-height: 1.35; letter-spacing: -0.01em;">
+                      ${escapeHtml(title)}
+                    </h1>
+                  </td>
+                </tr>
+              </table>
             </td>
           </tr>
           <!-- Body -->
           <tr>
-            <td style="padding: 24px;">
-              <div style="color: #374151; font-size: 16px; line-height: 1.6;">
+            <td class="email-body" bgcolor="#ffffff" style="padding: 28px 28px 24px 28px; background-color: #ffffff; color: #18181b;">
+              <div style="color: #18181b; font-size: 15px; line-height: 1.65;">
                 ${bodyHtml}
               </div>
+              ${subjectsHtml}
               ${
                 action
                   ? `
-              <!-- CTA Button -->
+              <!-- CTA button: bulletproof Outlook VML fallback + standard anchor for everyone else -->
               <table role="presentation" cellpadding="0" cellspacing="0" style="margin-top: 24px;">
                 <tr>
-                  <td>
-                    <a href="${escapeHtml(
-                      action.url
-                    )}" class="button" style="display: inline-block; padding: 12px 24px; background-color: ${buttonColor}; color: #ffffff; text-decoration: none; border-radius: 6px; font-weight: 600; font-size: 14px;">
-                      ${escapeHtml(action.label)}
+                  <td bgcolor="${buttonColor}" style="background-color: ${buttonColor}; border-radius: 6px;">
+                    <!--[if mso]>
+                    <v:roundrect xmlns:v="urn:schemas-microsoft-com:vml" xmlns:w="urn:schemas-microsoft-com:office:word" href="${escapeHtml(action.url)}" style="height:44px;v-text-anchor:middle;width:220px;" arcsize="14%" stroke="f" fillcolor="${buttonColor}">
+                      <w:anchorlock/>
+                      <center style="color:#ffffff;font-family:'Segoe UI',Arial,sans-serif;font-size:14px;font-weight:600;">${escapeHtml(action.label)}</center>
+                    </v:roundrect>
+                    <![endif]-->
+                    <!--[if !mso]><!-- -->
+                    <a href="${escapeHtml(action.url)}" class="button" style="display: inline-block; padding: 12px 22px; background-color: ${buttonColor}; border-radius: 6px; text-decoration: none; mso-hide: all;">
+                      <span class="button-label" style="color: #ffffff; font-family: -apple-system, BlinkMacSystemFont, 'Inter', 'Segoe UI', Roboto, Arial, sans-serif; font-size: 14px; font-weight: 600; line-height: 1.5; letter-spacing: 0.01em;">${escapeHtml(action.label)}</span>
                     </a>
+                    <!--<![endif]-->
                   </td>
                 </tr>
               </table>
+              <p class="mono" style="margin: 16px 0 0 0; color: #a1a1aa; font-size: 11px; line-height: 1.5; word-break: break-all;">
+                ${escapeHtml(action.url)}
+              </p>
               `
                   : ""
               }
@@ -221,14 +297,14 @@ export function wrapInEmailLayout(options: EmailLayoutOptions): string {
           </tr>
           <!-- Footer -->
           <tr>
-            <td style="background-color: #f9fafb; padding: 16px 24px; border-top: 1px solid #e5e7eb;">
-              <p style="margin: 0; color: #6b7280; font-size: 12px; line-height: 1.5; text-align: center;">
+            <td class="email-footer" style="background-color: #fafafa; padding: 16px 28px; border-top: 1px solid #e4e4e7;">
+              <p class="mono" style="margin: 0; color: #71717a; font-size: 11px; line-height: 1.5; text-align: center; letter-spacing: 0.02em;">
                 ${escapeHtml(footerText)}
               </p>
               ${
                 footerLinksHtml
                   ? `
-              <p style="margin: 8px 0 0 0; color: #6b7280; font-size: 12px; line-height: 1.5; text-align: center;">
+              <p style="margin: 8px 0 0 0; color: #71717a; font-size: 11px; line-height: 1.5; text-align: center;">
                 ${footerLinksHtml}
               </p>
               `

package/src/notification-strategy.ts

@@ -19,6 +19,22 @@ export type NotificationContactResolution =
 // Payload and Result Types
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+/**
+ * An entity affected by a notification, surfaced to the recipient as a
+ * chip/link/native element. Mirrors `NotificationSubject` from
+ * `@checkstack/notification-common` — duplicated here to avoid a runtime
+ * dependency from backend-api on notification-common.
+ *
+ * `kind` is namespaced as `<pluginId>.<localKind>` (e.g., `catalog.system`).
+ */
+export interface NotificationSubject {
+  kind: string;
+  id: string;
+  name: string;
+  url?: string;
+  status?: "healthy" | "unhealthy" | "degraded" | "unknown";
+}
+
 /**
  * The notification content to send via external channel.
  */
@@ -41,6 +57,15 @@ export interface NotificationPayload {
     label: string;
     url: string;
   };
+  /**
+   * Affected entities. Each strategy renders these in its native format
+   * (Slack section, Discord embed field, SMTP card, etc.). For text-only
+   * channels, render as a bulleted list with optional URLs.
+   *
+   * When `action` is null and `subjects` are present, the subject URLs are
+   * the recipient's only navigation paths.
+   */
+  subjects?: NotificationSubject[];
   /**
    * Source type identifier for filtering and templates.
    * Examples: "password-reset", "healthcheck.alert", "maintenance.reminder"

package/src/plugin-system.ts

@@ -99,6 +99,25 @@ export type BackendPluginRegistry = {
    * Multiple cleanup handlers can be registered; they run in LIFO order.
    */
   registerCleanup: (cleanup: () => Promise<void>) => void;
+  /**
+   * Declare notification subscription specs this plugin owns. Called
+   * synchronously during `register()` so the plugin loader can derive
+   * init-order dependencies from each spec's target: an emitter
+   * targeting `catalogSystemTarget` automatically waits for catalog's
+   * init + afterPluginsReady before its own. Plugins still call the
+   * notification-backend RPC `registerSubscriptionSpec` from
+   * afterPluginsReady — this declaration is purely for ordering.
+   *
+   * Each entry must carry an `ownerPlugin` that matches the calling
+   * plugin id, and a `target.ownerPlugin` describing the plugin that
+   * owns the target type the spec is bound to.
+   */
+  registerSubscriptionSpecs: (
+    specs: ReadonlyArray<{
+      readonly ownerPlugin: string;
+      readonly target: { readonly ownerPlugin: string };
+    }>,
+  ) => void;
   pluginManager: {
     getAllAccessRules: () => { id: string; description?: string }[];
   };