@checkstack/notification-backend 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @checkstack/notification-backend
 
+## 1.4.0
+
+### Minor Changes
+
+- 41c77f4: feat(notification): Phase 9 — delivered/failed triggers + send action
+
+  - New hooks `notificationHooks.delivered` and `notificationHooks.failed`,
+    fired from the shared `dispatchWithAttempt` funnel so every external
+    delivery path (subscription fan-out + transactional send) surfaces
+    uniformly. Persisted attempt rows are unchanged — the hooks are
+    best-effort and never block dispatch.
+  - Triggers `notification.delivered`, `notification.failed`, both
+    carrying `contextKey: (p) => p.notificationId` so an automation can
+    resume the run that opened the notification.
+  - Action `notification.send` wraps the existing `userType: "service"`
+    `sendTransactional` RPC, so automation-driven sends honour the same
+    per-user strategy preferences + contact resolution as code-driven
+    ones. Returns a `notification.send_result` artifact (per-strategy
+    outcome).
+
+  Plumbing note: `createNotificationRouter` now takes a late-bound
+  `getDispatchHookSink` getter. `register()` constructs an empty mutable
+  container that the router reads on every dispatch; `afterPluginsReady`
+  populates it with the real `emitHook`. Until populated (e.g. in
+  stripped-down test harnesses) delivery proceeds without firing the
+  hooks — no behaviour change for existing callers.
+
+### Patch Changes
+
+- Updated dependencies [e2d6f25]
+- Updated dependencies [41c77f4]
+- Updated dependencies [e1a2077]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [41c77f4]
+- Updated dependencies [6d52276]
+- Updated dependencies [6d52276]
+- Updated dependencies [35bc682]
+  - @checkstack/automation-backend@0.2.0
+  - @checkstack/common@0.12.0
+  - @checkstack/backend-api@0.18.0
+  - @checkstack/auth-backend@0.4.31
+  - @checkstack/auth-common@0.7.2
+  - @checkstack/notification-common@1.2.1
+  - @checkstack/signal-common@0.2.5
+  - @checkstack/cache-api@0.3.6
+  - @checkstack/queue-api@0.3.6
+  - @checkstack/cache-utils@0.2.11
+
+## 1.3.0
+
+### Minor Changes
+
+- ba07ae2: Quiet down notification spam on flapping systems, auto-open incidents when a check goes critical, and let operators land directly on the broken checks.
+
+  Notification policy lives **per healthcheck assignment** (one row per `system × configuration`). Different checks on the same system are fully independent — disabling a setting on one check does not affect the others. Defaults preserve existing behaviour for `suppressDeEscalations`; **auto-incident defaults to on** for new and existing assignments.
+
+  - **`suppressDeEscalations`** (off by default). When on, transitions from a worse state to a better-but-still-failing state (e.g. `unhealthy → degraded`) no longer fire a notification. Escalations and full recoveries to `healthy` are unaffected. Resolved per assignment (the just-ran check is the one driving any aggregate transition).
+  - **`autoOpenIncidentOnUnhealthy`** (on by default). Either of two independent triggers can open the auto-incident:
+    - **`sustainedUnhealthyTrigger`** (default 30 min) — opens when the check stays continuously unhealthy for the configured duration. Catches real outages.
+    - **`flappingTrigger`** (default 3 transitions in 60 min) — opens when the check flips to unhealthy that many times in the window. Catches persistent flapping where each unhealthy phase is too brief for the sustained trigger.
+      Each trigger can be individually disabled. One incident per system: triggering checks attach to an existing active auto-incident.
+  - **`useNotificationSuppression`** (on by default, only meaningful when auto-open is on). Controls whether the auto-opened incident is created with `suppressNotifications: true` — leaving this off opens the incident but still pings operators on each transition.
+  - **`skipDuringMaintenance`** (on by default). No auto-incident is opened while the system has an active maintenance window with suppression. The system is intentionally down and shouldn't trip the on-call.
+  - **`autoCloseAfterMinutes`** (default 30). Auto-close cooldown is now per-assignment and snapshotted per-incident at open time — later policy edits don't alter in-flight incidents. Setting `null` ("Never auto-close") leaves the incident for manual resolution.
+  - **Require-recovery rule.** After any auto-incident closes (manual or auto), no new auto-incident can open until the check has logged at least one healthy run. Prevents a "operator dismissed but it's still broken" loop.
+  - **Auto-close worker** ticks every 60s and resolves auto-opened incidents whose systems have been healthy for their per-row `cooldownMinutes`. Rows with `null` cooldown are skipped entirely. Per-incident: failed close attempts are logged but never abort the sweep.
+  - **`incidentResolved` hook subscriber** syncs the auto-incident mapping when an operator manually resolves the incident, so the require-recovery rule sees the close immediately.
+  - **Platform-wide defaults.** New admin RPCs `getPlatformNotificationDefaults` / `setPlatformNotificationDefaults` (under the existing `healthcheck.configuration.{read,manage}` access rules) let operators set notification policy once for the whole instance. Per-assignment rows with `notificationPolicy: null` inherit the platform defaults at read time. UI: a "Notification defaults" button in the Assignment IDE opens a modal editor. The per-assignment Notifications panel shows an inheritance banner — "Using platform defaults" (read-only) with an "Override" button, or "Custom override" with a "Use platform defaults" button to revert. The all-or-nothing model keeps the mental model simple: each assignment is either fully inherited or fully overridden.
+  - **New service-level RPCs** on the incident plugin (`createAutoIncident`, `resolveAutoIncident`) let other plugins open/close incidents without a user context. Reused by the healthcheck auto-incident flow.
+  - **Health-state notification CTA** now deep-links to `?filter=failing` on the system detail page for non-recovery transitions (label changes to "View failing checks"). The system overview gains an `All / Failing / Healthy` segmented filter wired to the same `?filter=…` param.
+  - **Notification bell badge** now counts collapse groups instead of raw rows, so the number matches what the user sees in the notifications list. Built on `COUNT(DISTINCT COALESCE(collapse_key, id))` — notifications without a collapse key still each count as one.
+  - **`statusFilter` on `getHistory` / `getDetailedHistory`** lets the run-history page and the drawer's Recent Runs panel filter to `All / Healthy / Failing` via shared pills, with the page resetting to the first page on filter change.
+  - **Pagination defaults aligned with selector options.** Several pages defaulted to a page size (5 or 20) that wasn't in the dropdown's options (`[10, 25, 50, 100]`), so the page-size `<Select>` rendered empty. The drawer's Recent Runs now defaults to 10; the Run History, History List, and Delivery Logs pages now default to 25.
+
+  Includes Drizzle migrations adding the `notification_policy` jsonb column to `system_health_checks`, plus two new tables: `health_check_unhealthy_transitions` (for threshold counting) and `health_check_auto_incidents` (for mapping back to incident ids during auto-close).
+
+### Patch Changes
+
+- @checkstack/backend-api@0.17.1
+- @checkstack/auth-backend@0.4.30
+- @checkstack/cache-api@0.3.5
+- @checkstack/queue-api@0.3.5
+- @checkstack/cache-utils@0.2.10
+
 ## 1.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/notification-backend",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -15,24 +15,25 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@checkstack/notification-common": "1.1.1",
-    "@checkstack/backend-api": "0.16.0",
-    "@checkstack/cache-api": "0.3.3",
-    "@checkstack/cache-utils": "0.2.8",
-    "@checkstack/signal-common": "0.2.3",
-    "@checkstack/queue-api": "0.3.3",
-    "@checkstack/auth-backend": "0.4.28",
-    "@checkstack/auth-common": "0.7.0",
+    "@checkstack/notification-common": "1.2.0",
+    "@checkstack/backend-api": "0.17.1",
+    "@checkstack/automation-backend": "0.1.0",
+    "@checkstack/cache-api": "0.3.5",
+    "@checkstack/cache-utils": "0.2.10",
+    "@checkstack/signal-common": "0.2.4",
+    "@checkstack/queue-api": "0.3.5",
+    "@checkstack/auth-backend": "0.4.30",
+    "@checkstack/auth-common": "0.7.1",
     "drizzle-orm": "^0.45.0",
     "zod": "^4.2.1",
-    "@checkstack/common": "0.10.0",
+    "@checkstack/common": "0.11.0",
     "@orpc/server": "^1.13.2"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/scripts": "0.3.2",
+    "@checkstack/scripts": "0.3.3",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/test-utils-backend": "0.1.28",
+    "@checkstack/test-utils-backend": "0.1.30",
     "@types/node": "^20.0.0",
     "drizzle-kit": "^0.31.10",
     "typescript": "^5.0.0"

package/src/automations.test.ts

@@ -0,0 +1,263 @@
+/**
+ * Behaviour tests for the notification automation triggers + send action.
+ *
+ * The triggers wrap two new hooks fired from `dispatchWithAttempt`,
+ * so the surface tested here is dataclass-ish (payload validation +
+ * contextKey extraction).
+ *
+ * The send action delegates to `notificationClient.sendTransactional`.
+ * We mock the rpcClient.forPlugin(...) plumbing with a tiny shim so we
+ * can exercise the happy / zero-deliveries / thrown-error paths and
+ * lock down the artifact mapping.
+ */
+import { describe, expect, it, mock } from "bun:test";
+import type { Logger, RpcClient } from "@checkstack/backend-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+import {
+  createNotificationActions,
+  notificationDeliveredTrigger,
+  notificationFailedTrigger,
+  notificationSendArtifactType,
+  notificationTriggers,
+} from "./automations";
+
+const logger = createMockLogger() as Logger;
+
+const ctxBase = {
+  runId: "run-1",
+  automationId: "auto-1",
+  contextKey: null,
+  logger,
+  getService: async <T,>(): Promise<T> => {
+    throw new Error("not used");
+  },
+};
+
+// ─── Triggers ──────────────────────────────────────────────────────────
+
+describe("notification triggers", () => {
+  it("exposes two triggers in a stable order", () => {
+    expect(notificationTriggers).toHaveLength(2);
+    expect(notificationTriggers[0]).toBe(
+      notificationDeliveredTrigger as (typeof notificationTriggers)[number],
+    );
+    expect(notificationTriggers[1]).toBe(
+      notificationFailedTrigger as (typeof notificationTriggers)[number],
+    );
+  });
+
+  it("extracts notificationId as the contextKey", () => {
+    const delivered = {
+      notificationId: "n-1",
+      strategyQualifiedId: "email.smtp",
+      durationMs: 42,
+      timestamp: "2026-05-29T11:00:00Z",
+    };
+    expect(notificationDeliveredTrigger.contextKey?.(delivered)).toBe("n-1");
+
+    const failed = {
+      notificationId: "n-2",
+      strategyQualifiedId: "webex.bot",
+      errorMessage: "401 Unauthorized",
+      durationMs: 12,
+      timestamp: "2026-05-29T11:00:00Z",
+    };
+    expect(notificationFailedTrigger.contextKey?.(failed)).toBe("n-2");
+  });
+
+  it("rejects payloads missing required fields", () => {
+    const bad = notificationFailedTrigger.payloadSchema.safeParse({
+      notificationId: "n-2",
+      strategyQualifiedId: "webex.bot",
+      durationMs: 12,
+      timestamp: "2026-05-29T11:00:00Z",
+    });
+    expect(bad.success).toBe(false);
+  });
+});
+
+// ─── Artifact ──────────────────────────────────────────────────────────
+
+describe("notificationSendArtifactType", () => {
+  it("validates the canonical artifact shape", () => {
+    const ok = notificationSendArtifactType.schema.safeParse({
+      userId: "user-1",
+      deliveredCount: 2,
+      results: [
+        { strategyId: "email.smtp", success: true },
+        { strategyId: "webex.bot", success: false, error: "401" },
+      ],
+    });
+    expect(ok.success).toBe(true);
+  });
+});
+
+// ─── Action: notification.send ─────────────────────────────────────────
+
+interface SendTransactionalResult {
+  deliveredCount: number;
+  results: Array<{ strategyId: string; success: boolean; error?: string }>;
+}
+
+function makeRpcClient(behaviour:
+  | { ok: true; result: SendTransactionalResult }
+  | { ok: false; error: Error },
+): RpcClient & { sendMock: ReturnType<typeof mock> } {
+  const sendMock = mock(async (_input: unknown) => {
+    if (!behaviour.ok) throw behaviour.error;
+    return behaviour.result;
+  });
+  return {
+    forPlugin: () => ({ sendTransactional: sendMock }),
+    sendMock,
+  } as unknown as RpcClient & { sendMock: ReturnType<typeof mock> };
+}
+
+describe("notification.send", () => {
+  it("returns success when at least one strategy delivers and emits a per-strategy artifact", async () => {
+    const rpcClient = makeRpcClient({
+      ok: true,
+      result: {
+        deliveredCount: 1,
+        results: [
+          { strategyId: "email.smtp", success: true },
+          { strategyId: "webex.bot", success: false, error: "401" },
+        ],
+      },
+    });
+    const [send] = createNotificationActions({ rpcClient });
+
+    const result = await send!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        userId: "user-1",
+        title: "Hi",
+        body: "Hello",
+      } as never,
+    });
+
+    expect(result.success).toBe(true);
+    if (!result.success) return;
+    expect(result.externalId).toBe("user-1");
+    const artifact = result.artifact as {
+      userId: string;
+      deliveredCount: number;
+      results: Array<{ strategyId: string; success: boolean }>;
+    };
+    expect(artifact.deliveredCount).toBe(1);
+    expect(artifact.results).toHaveLength(2);
+
+    // sendTransactional was called with the operator-supplied fields.
+    const call = rpcClient.sendMock.mock.calls[0]![0] as {
+      userId: string;
+      notification: { title: string; body: string };
+    };
+    expect(call.userId).toBe("user-1");
+    expect(call.notification.title).toBe("Hi");
+    expect(call.notification.body).toBe("Hello");
+  });
+
+  it("returns success=false when no strategy delivered but still emits the artifact for audit", async () => {
+    const rpcClient = makeRpcClient({
+      ok: true,
+      result: {
+        deliveredCount: 0,
+        results: [
+          { strategyId: "email.smtp", success: false, error: "no contact" },
+        ],
+      },
+    });
+    const [send] = createNotificationActions({ rpcClient });
+
+    const result = await send!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        userId: "user-1",
+        title: "Hi",
+        body: "Hello",
+      } as never,
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    const artifact = result.artifact as { deliveredCount: number };
+    expect(artifact.deliveredCount).toBe(0);
+  });
+
+  it("forwards an action button to sendTransactional when both label + url are set", async () => {
+    const rpcClient = makeRpcClient({
+      ok: true,
+      result: { deliveredCount: 1, results: [] },
+    });
+    const [send] = createNotificationActions({ rpcClient });
+
+    await send!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        userId: "user-1",
+        title: "Hi",
+        body: "Hello",
+        actionLabel: "Open",
+        actionUrl: "https://example.com",
+      } as never,
+    });
+
+    const call = rpcClient.sendMock.mock.calls[0]![0] as {
+      notification: { action?: { label: string; url: string } };
+    };
+    expect(call.notification.action).toEqual({
+      label: "Open",
+      url: "https://example.com",
+    });
+  });
+
+  it("omits the action object when only one of label/url is set", async () => {
+    const rpcClient = makeRpcClient({
+      ok: true,
+      result: { deliveredCount: 1, results: [] },
+    });
+    const [send] = createNotificationActions({ rpcClient });
+
+    await send!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        userId: "user-1",
+        title: "Hi",
+        body: "Hello",
+        actionUrl: "https://example.com",
+      } as never,
+    });
+
+    const call = rpcClient.sendMock.mock.calls[0]![0] as {
+      notification: { action?: unknown };
+    };
+    expect(call.notification.action).toBeUndefined();
+  });
+
+  it("returns failure when sendTransactional throws", async () => {
+    const rpcClient = makeRpcClient({
+      ok: false,
+      error: new Error("rpc unreachable"),
+    });
+    const [send] = createNotificationActions({ rpcClient });
+
+    const result = await send!.execute({
+      ...ctxBase,
+      consumedArtifacts: {},
+      config: {
+        userId: "user-1",
+        title: "Hi",
+        body: "Hello",
+      } as never,
+    });
+
+    expect(result.success).toBe(false);
+    if (result.success) return;
+    expect(result.error).toMatch(/rpc unreachable/);
+  });
+});

package/src/automations.ts

@@ -0,0 +1,200 @@
+/**
+ * Notification triggers + actions registered with the Automation Platform.
+ *
+ * Triggers expose the new `notificationHooks.delivered` and
+ * `notificationHooks.failed` events as automation entry points. The
+ * hooks are fired from the shared `dispatchWithAttempt` funnel so every
+ * external delivery path (subscription fan-out, transactional send,
+ * future fan-outs) surfaces uniformly.
+ *
+ * The `notification.send` action wraps the existing `sendTransactional`
+ * RPC — that endpoint is already `userType: "service"`, so the
+ * dispatch engine's rpcClient can invoke it directly. Centralising on
+ * `sendTransactional` means automation-driven sends honour the same
+ * per-user strategy preferences + contact resolution as code-driven
+ * ones.
+ */
+import { z } from "zod";
+import { Versioned, type RpcClient } from "@checkstack/backend-api";
+import type {
+  ActionDefinition,
+  TriggerDefinition,
+} from "@checkstack/automation-backend";
+import { extractErrorMessage } from "@checkstack/common";
+import { NotificationApi } from "@checkstack/notification-common";
+
+import { notificationHooks } from "./hooks";
+
+// ─── Payload schemas — match the hook payloads exactly ─────────────────
+
+const deliveredPayloadSchema = z.object({
+  notificationId: z.string(),
+  strategyQualifiedId: z.string(),
+  durationMs: z.number(),
+  timestamp: z.string(),
+});
+
+const failedPayloadSchema = z.object({
+  notificationId: z.string(),
+  strategyQualifiedId: z.string(),
+  errorMessage: z.string(),
+  durationMs: z.number(),
+  timestamp: z.string(),
+});
+
+// ─── Triggers ──────────────────────────────────────────────────────────
+
+export const notificationDeliveredTrigger: TriggerDefinition<
+  z.infer<typeof deliveredPayloadSchema>
+> = {
+  id: "delivered",
+  displayName: "Notification Delivered",
+  description: "Fires when an external delivery attempt succeeded",
+  category: "Notifications",
+  icon: "BellRing",
+  payloadSchema: deliveredPayloadSchema,
+  hook: notificationHooks.delivered,
+  contextKey: (p) => p.notificationId,
+};
+
+export const notificationFailedTrigger: TriggerDefinition<
+  z.infer<typeof failedPayloadSchema>
+> = {
+  id: "failed",
+  displayName: "Notification Failed",
+  description: "Fires when an external delivery attempt failed",
+  category: "Notifications",
+  icon: "BellOff",
+  payloadSchema: failedPayloadSchema,
+  hook: notificationHooks.failed,
+  contextKey: (p) => p.notificationId,
+};
+
+export const notificationTriggers: TriggerDefinition<unknown>[] = [
+  notificationDeliveredTrigger as TriggerDefinition<unknown>,
+  notificationFailedTrigger as TriggerDefinition<unknown>,
+];
+
+// ─── Action: notification.send ─────────────────────────────────────────
+
+const notificationSendConfigSchema = z.object({
+  userId: z.string().min(1).describe("Target user to notify"),
+  title: z.string().min(1).describe("Notification title"),
+  body: z.string().min(1).describe("Notification body (supports markdown)"),
+  importance: z
+    .enum(["info", "warning", "critical"])
+    .optional()
+    .describe("Severity; defaults to 'info'"),
+  actionLabel: z
+    .string()
+    .optional()
+    .describe("Optional action button label"),
+  actionUrl: z
+    .string()
+    .optional()
+    .describe("Optional action button URL"),
+});
+
+export type NotificationSendConfig = z.infer<
+  typeof notificationSendConfigSchema
+>;
+
+// ─── Artifact type ─────────────────────────────────────────────────────
+
+const notificationSendArtifactSchema = z.object({
+  userId: z.string(),
+  deliveredCount: z
+    .number()
+    .describe("Number of strategies that delivered successfully"),
+  results: z.array(
+    z.object({
+      strategyId: z.string(),
+      success: z.boolean(),
+      error: z.string().optional(),
+    }),
+  ),
+});
+
+export type NotificationSendArtifact = z.infer<
+  typeof notificationSendArtifactSchema
+>;
+
+export const notificationSendArtifactType = {
+  id: "send_result",
+  displayName: "Notification Send Result",
+  description:
+    "Per-strategy outcome from a `notification.send` automation action",
+  schema: notificationSendArtifactSchema,
+} as const;
+
+// ─── Action factory ────────────────────────────────────────────────────
+
+export interface NotificationActionDeps {
+  /**
+   * Plugin rpcClient. The action invokes
+   * `sendTransactional` (service-mode) so notification-backend's
+   * existing dispatch loop runs — same strategy fan-out + per-attempt
+   * persistence + (now) delivered/failed hook emission as a
+   * code-driven send.
+   */
+  rpcClient: RpcClient;
+}
+
+export function createNotificationActions(
+  deps: NotificationActionDeps,
+): ActionDefinition<unknown, unknown>[] {
+  const sendAction: ActionDefinition<
+    NotificationSendConfig,
+    NotificationSendArtifact
+  > = {
+    id: "send",
+    displayName: "Send Notification",
+    description:
+      "Send a transactional notification to a specific user via all enabled strategies",
+    category: "Notifications",
+    icon: "BellRing",
+    config: new Versioned({
+      version: 1,
+      schema: notificationSendConfigSchema,
+    }),
+    produces: "notification.send_result",
+    execute: async ({ config, logger }) => {
+      const notificationClient = deps.rpcClient.forPlugin(NotificationApi);
+      const action =
+        config.actionLabel && config.actionUrl
+          ? { label: config.actionLabel, url: config.actionUrl }
+          : undefined;
+      try {
+        const result = await notificationClient.sendTransactional({
+          userId: config.userId,
+          notification: {
+            title: config.title,
+            body: config.body,
+            importance: config.importance,
+            action,
+          },
+        });
+        logger.info(
+          `Automation sent notification to ${config.userId} (${result.deliveredCount} delivered)`,
+        );
+        return {
+          success: result.deliveredCount > 0,
+          // No single externalId — but recording the user keeps the
+          // run-detail UI useful when there are several send steps.
+          externalId: config.userId,
+          artifact: {
+            userId: config.userId,
+            deliveredCount: result.deliveredCount,
+            results: result.results,
+          },
+        };
+      } catch (error) {
+        const message = extractErrorMessage(error);
+        logger.error(`Notification send failed: ${message}`);
+        return { success: false, error: message };
+      }
+    },
+  };
+
+  return [sendAction as ActionDefinition<unknown, unknown>];
+}

package/src/delivery-attempts.ts

@@ -64,6 +64,29 @@ export interface SendableStrategy {
   ) => Promise<{ success: boolean; error?: string }>;
 }
 
+/**
+ * Optional hook-emission callbacks the dispatch funnel can fire to
+ * surface the per-attempt outcome to other plugins (e.g. as
+ * automation triggers). Bound from `afterPluginsReady` where
+ * `emitHook` becomes available — when not provided, no hook fires
+ * and behaviour is unchanged.
+ */
+export interface DispatchAttemptHookSink {
+  onDelivered: (event: {
+    notificationId: string;
+    strategyQualifiedId: string;
+    durationMs: number;
+    timestamp: string;
+  }) => Promise<void>;
+  onFailed: (event: {
+    notificationId: string;
+    strategyQualifiedId: string;
+    errorMessage: string;
+    durationMs: number;
+    timestamp: string;
+  }) => Promise<void>;
+}
+
 /**
  * Invoke `strategy.send(...)` with duration measurement + best-effort
  * attempt persistence on both branches. Centralised so the same
@@ -88,14 +111,17 @@ export const dispatchWithAttempt = async ({
   strategy,
   sendContext,
   notificationId,
+  hookSink,
 }: {
   database: SafeDatabase<typeof schema>;
   logger: Logger;
   strategy: SendableStrategy;
   sendContext: NotificationSendContext<unknown, unknown, unknown>;
   notificationId: string;
+  hookSink?: DispatchAttemptHookSink;
 }): Promise<void> => {
   const startMs = performance.now();
+  const timestamp = new Date().toISOString();
   try {
     const result = await strategy.send(sendContext);
     const durationMs = Math.round(performance.now() - startMs);
@@ -122,8 +148,36 @@ export const dispatchWithAttempt = async ({
             durationMs,
           },
     });
+    // Fire the per-attempt outcome hook for automation triggers.
+    // Best-effort: failures here are logged but never propagated, the
+    // same as the persist-attempt guarantee.
+    if (hookSink) {
+      try {
+        const hookCall = result.success
+          ? hookSink.onDelivered({
+              notificationId,
+              strategyQualifiedId: strategy.qualifiedId,
+              durationMs,
+              timestamp,
+            })
+          : hookSink.onFailed({
+              notificationId,
+              strategyQualifiedId: strategy.qualifiedId,
+              errorMessage: result.error ?? "Strategy reported failure",
+              durationMs,
+              timestamp,
+            });
+        await hookCall;
+      } catch (hookError) {
+        logger.error(
+          `[external-delivery] Hook sink failed for ${strategy.qualifiedId}:`,
+          hookError,
+        );
+      }
+    }
   } catch (sendError) {
     const durationMs = Math.round(performance.now() - startMs);
+    const sanitisedMessage = extractErrorMessage(sendError);
     logger.error(
       `[external-delivery] Error sending via ${strategy.qualifiedId}:`,
       sendError,
@@ -138,9 +192,25 @@ export const dispatchWithAttempt = async ({
         // `extractErrorMessage` sanitises arbitrary thrown values -
         // never persist the raw error object since it may embed
         // webhook URLs / tokens via the strategy's send context.
-        errorMessage: extractErrorMessage(sendError),
+        errorMessage: sanitisedMessage,
         durationMs,
       },
     });
+    if (hookSink) {
+      try {
+        await hookSink.onFailed({
+          notificationId,
+          strategyQualifiedId: strategy.qualifiedId,
+          errorMessage: sanitisedMessage,
+          durationMs,
+          timestamp,
+        });
+      } catch (hookError) {
+        logger.error(
+          `[external-delivery] Hook sink failed for ${strategy.qualifiedId}:`,
+          hookError,
+        );
+      }
+    }
   }
 };

package/src/hooks.ts

@@ -0,0 +1,38 @@
+import { createHook } from "@checkstack/backend-api";
+
+/**
+ * Notification-backend hooks for cross-plugin reaction.
+ *
+ * Emitted from the shared `dispatchWithAttempt` funnel — so every
+ * external delivery (whether triggered by `notifyForSubscription`,
+ * `sendTransactional`, or any future fan-out path) is observable via
+ * the same two hooks. Internal-only notifications (those not sent via
+ * an external strategy) don't fire these.
+ */
+export const notificationHooks = {
+  /**
+   * Emitted when a delivery attempt succeeded for a specific strategy.
+   * Carries enough to correlate against the persisted attempt row
+   * (`notificationDeliveryAttempts.notificationId + strategyQualifiedId`)
+   * without forcing subscribers to round-trip the DB.
+   */
+  delivered: createHook<{
+    notificationId: string;
+    strategyQualifiedId: string;
+    durationMs: number;
+    timestamp: string;
+  }>("notification.delivered"),
+
+  /**
+   * Emitted when a delivery attempt failed (either the strategy
+   * returned `success: false` or `.send(...)` threw). `errorMessage`
+   * is the same already-sanitised string written to the attempt row.
+   */
+  failed: createHook<{
+    notificationId: string;
+    strategyQualifiedId: string;
+    errorMessage: string;
+    durationMs: number;
+    timestamp: string;
+  }>("notification.failed"),
+} as const;

package/src/index.ts

@@ -25,6 +25,18 @@ import { createNotificationCache } from "./cache";
 import { authHooks } from "@checkstack/auth-backend";
 import { createOAuthCallbackHandler } from "./oauth-callback-handler";
 import { createStrategyService } from "./strategy-service";
+import {
+  automationActionExtensionPoint,
+  automationArtifactTypeExtensionPoint,
+  automationTriggerExtensionPoint,
+} from "@checkstack/automation-backend";
+import {
+  createNotificationActions,
+  notificationSendArtifactType,
+  notificationTriggers,
+} from "./automations";
+import { notificationHooks } from "./hooks";
+import type { DispatchAttemptHookSink } from "./delivery-attempts";
 
 // ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 // Extension Point
@@ -158,6 +170,23 @@ export default createBackendPlugin({
       },
     });
 
+    // ─── Automation Platform: triggers + artifact type ─────────────────
+    const automationTriggers = env.getExtensionPoint(
+      automationTriggerExtensionPoint,
+    );
+    for (const trigger of notificationTriggers) {
+      automationTriggers.registerTrigger(trigger, pluginMetadata);
+    }
+    env
+      .getExtensionPoint(automationArtifactTypeExtensionPoint)
+      .registerArtifactType(notificationSendArtifactType, pluginMetadata);
+
+    // Late-bound hook sink. `afterPluginsReady` populates it once
+    // `emitHook` is available; the router reads it lazily on every
+    // dispatch, so until populated, delivery still works but no
+    // automation triggers fire.
+    const dispatchHookSinkRef: { current?: DispatchAttemptHookSink } = {};
+
     env.registerInit({
       schema,
       deps: {
@@ -206,6 +235,7 @@ export default createBackendPlugin({
           rpcClient,
           logger,
           cache,
+          () => dispatchHookSinkRef.current,
         );
         rpc.registerRouter(router, notificationContract);
 
@@ -220,9 +250,35 @@ export default createBackendPlugin({
 
         logger.debug("✅ Notification Backend initialized.");
       },
-      afterPluginsReady: async ({ database, logger, onHook, emitHook }) => {
+      afterPluginsReady: async ({
+        database,
+        logger,
+        onHook,
+        emitHook,
+        rpcClient,
+      }) => {
         const db = database;
 
+        // Populate the late-bound dispatch hook sink. After this
+        // point every external delivery attempt also fires the
+        // matching automation trigger.
+        dispatchHookSinkRef.current = {
+          onDelivered: (event) =>
+            emitHook(notificationHooks.delivered, event),
+          onFailed: (event) =>
+            emitHook(notificationHooks.failed, event),
+        };
+
+        // Register automation actions now that `rpcClient` (= the
+        // service-mode caller for `sendTransactional`) is available
+        // and all other plugins have registered their access rules.
+        const automationActions = env.getExtensionPoint(
+          automationActionExtensionPoint,
+        );
+        for (const action of createNotificationActions({ rpcClient })) {
+          automationActions.registerAction(action, pluginMetadata);
+        }
+
         // Log registered strategies
         const strategies = strategyRegistry.getStrategies();
         logger.debug(

package/src/router.ts

@@ -144,6 +144,19 @@ export const createNotificationRouter = (
   rpcApi: RpcClient,
   logger: Logger,
   cache: NotificationCache,
+  /**
+   * Late-bound: returns the dispatch hook sink (delivered/failed
+   * automation triggers). `init()` wires this with a closure on a
+   * mutable container; `afterPluginsReady()` populates the container
+   * once `emitHook` is available. Until then — and on stripped-down
+   * test setups — the getter returns `undefined` and hook firing is
+   * skipped without affecting persisted delivery attempts.
+   */
+  getDispatchHookSink: () =>
+    | import("./delivery-attempts").DispatchAttemptHookSink
+    | undefined = () => {
+    return;
+  },
 ) => {
   // Create strategy service for config management
   const strategyService: StrategyService = createStrategyService({
@@ -298,6 +311,7 @@ export const createNotificationRouter = (
           strategy,
           sendContext,
           notificationId,
+          hookSink: getDispatchHookSink(),
         });
       } catch (error) {
         // Log error but continue - external delivery shouldn't block in-app

package/src/service.ts

@@ -1,5 +1,5 @@
 import type { SafeDatabase } from "@checkstack/backend-api";
-import { eq, and, count, desc, lt } from "drizzle-orm";
+import { eq, and, count, countDistinct, desc, lt, sql } from "drizzle-orm";
 import * as schema from "./schema";
 
 // --- Internal service functions for router (not namespaced) ---
@@ -41,14 +41,21 @@ export async function getUserNotifications(
 }
 
 /**
- * Get unread count for a user
+ * Get unread count for a user, counted by collapse group so the bell
+ * badge matches the number of cards the user actually sees in the
+ * notifications list. Notifications without a collapse key each count
+ * as their own group via `COALESCE(collapse_key, id::text)`.
  */
 export async function getUnreadCount(
   db: SafeDatabase<typeof schema>,
   userId: string
 ): Promise<number> {
   const result = await db
-    .select({ count: count() })
+    .select({
+      count: countDistinct(
+        sql`COALESCE(${schema.notifications.collapseKey}, ${schema.notifications.id}::text)`
+      ),
+    })
     .from(schema.notifications)
     .where(
       and(

package/tsconfig.json

@@ -10,6 +10,9 @@
     {
       "path": "../auth-common"
     },
+    {
+      "path": "../automation-backend"
+    },
     {
       "path": "../backend-api"
     },