@checkstack/notification-backend 0.2.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,182 @@
 # @checkstack/notification-backend
 
+## 1.0.0
+
+### Major Changes
+
+- 32d52c6: feat: notification target pattern + per-spec subscriptions
+
+  Replaces the all-or-nothing catalog system/group notification model with a
+  platform-level target pattern. Each notification-emitting plugin declares
+  _subscription specs_ against typed _target_ objects exported from the
+  target's owning plugin (catalog ships `catalogSystemTarget` and
+  `catalogGroupTarget`). Notification-backend handles every per-resource
+  group lifecycle, parent-edge inheritance, and legacy-subscription seeding
+  — plugins never author groupId helpers, lifecycle hooks, or migration
+  code again.
+
+  **Plugin-author surface area is now ~12 lines per emitter:**
+
+  ```ts
+  // <plugin>-common
+  const { defineSubscription } = createSubscriptionFactory(pluginMetadata);
+  export const fooSystemSubscription = defineSubscription({
+    localId: "system",
+    target: catalogSystemTarget,
+    display: { title: "Foo Alerts", description: "...", iconName: "Bell" },
+  });
+
+  // <plugin>-backend register()
+  env.registerSubscriptionSpecs([fooSystemSubscription]);
+  //   ^ feeds the plugin loader's dependency sorter — each spec's
+  //     target.ownerPlugin becomes an implicit init-order dep, so this
+  //     plugin automatically waits for catalog (the target owner) to
+  //     finish init + afterPluginsReady before its own runs.
+
+  // <plugin>-backend afterPluginsReady
+  await notificationClient.registerSubscriptionSpec(
+    specToRegistration(fooSystemSubscription)
+  );
+  // dispatch
+  await notificationClient.notifyForSubscription({
+    specId: fooSystemSubscription.specId,
+    resourceKeys: [systemId],
+    title,
+    body,
+    importance,
+    action,
+    collapseKey,
+    subjects,
+  });
+
+  // <plugin>-frontend
+  createNotificationSubscriptionExtension({ spec: fooSystemSubscription });
+  ```
+
+  **Migrated plugins**: anomaly, incident, maintenance, healthcheck,
+  dependency. Each lost its bespoke `notification-groups.ts`,
+  `bootstrap*NotificationGroups`, `ensure*Group`, and inheritance walk —
+  all of that is now centralized in notification-backend's
+  `subscription-engine`.
+
+  **Plugin loader change** (`@checkstack/backend-api`,
+  `@checkstack/backend`): the register-time API gains
+  `env.registerSubscriptionSpecs([...specs])`. The dependency sorter
+  walks `spec.target.ownerPlugin` for every declared spec and adds the
+  target owner as an init-order dependency of the emitting plugin. This
+  guarantees that catalog (the owner of the platform's `system` and
+  `group` targets) completes init + afterPluginsReady before any
+  emitting plugin tries to register its specs against the notification
+  service — no string-prefix heuristics, no manual `dependsOnPlugins`
+  list, no stub rows. Plugins that fail to declare their specs at
+  register time get a clear `Target type X is not registered. Did the
+emitting plugin declare this spec via env.registerSubscriptionSpecs?`
+  error from the dispatcher.
+
+  **Removed** (no backwards compat):
+
+  - `catalogClient.notifySystemSubscribers` and
+    `catalogClient.notifyManySystemSubscribers`
+  - `notificationClient.notifyUsers` and `notificationClient.notifyGroups`
+    as direct dispatch primitives — replaced by spec-bound
+    `notifyForSubscription`
+  - catalog's `bootstrapNotificationGroups` (replaced by
+    `bootstrapNotificationTargets`)
+
+  **Enforcement**: the dispatcher rejects calls referencing unregistered
+  specIds, specs owned by other plugins, or resourceKeys that haven't been
+  pushed via `upsertNotificationResource`. Display metadata for any
+  groupId is recoverable via the spec registry, so audit lists render
+  correct labels even when an emitter's frontend isn't loaded.
+
+  **Per-field anomaly mute** keeps working — it now lives inside the
+  generic SubscriptionRow's optional `SubControls` panel
+  (`AnomalyFieldMuteList`), exposed through the catalog system detail
+  page's notifications card.
+
+  The catalog system detail page renders a "Notifications" card hosting
+  `SystemNotificationSubscriptionsSlot`. The matching group surface is
+  not yet rendered — group-level subscriptions are wired end-to-end on
+  the backend; a follow-up will add the host UI.
+
+  **Migration of existing subscribers**: target types declare a
+  `legacyGroupIdTemplate`; on first registration of each spec,
+  notification-backend reads subscribers from the legacy
+  `catalog.system.<id>` / `catalog.group.<id>` groups and seeds the new
+  spec groups exactly once per (spec × resource) pair, tracked in
+  `subscription_migrations`. Anomaly stays opt-in (its target also
+  declares the template, but the user-explicit nature of the original
+  opt-in flow means the seeding produces the same set of subscribers
+  they already had).
+
+### Minor Changes
+
+- 32d52c6: 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.).
+
+### 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]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+- Updated dependencies [32d52c6]
+  - @checkstack/notification-common@1.0.0
+  - @checkstack/backend-api@0.14.0
+  - @checkstack/auth-backend@0.4.22
+  - @checkstack/auth-common@0.6.4
+  - @checkstack/cache-api@0.2.2
+  - @checkstack/queue-api@0.2.16
+  - @checkstack/cache-utils@0.2.2
+
+## 0.2.1
+
+### Patch Changes
+
+- Updated dependencies [208ad71]
+  - @checkstack/signal-common@0.2.0
+  - @checkstack/notification-common@0.3.0
+  - @checkstack/backend-api@0.13.1
+  - @checkstack/auth-backend@0.4.21
+  - @checkstack/cache-api@0.2.1
+  - @checkstack/queue-api@0.2.15
+  - @checkstack/cache-utils@0.2.1
+
 ## 0.2.0
 
 ### Minor Changes

package/drizzle/0005_material_mauler.sql

@@ -0,0 +1,3 @@
+ALTER TABLE "notifications" ADD COLUMN "subjects" jsonb;--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "notifications_user_collapse_idx" ON "notifications" USING btree ("user_id","group_id");--> statement-breakpoint
+CREATE INDEX IF NOT EXISTS "notifications_user_created_idx" ON "notifications" USING btree ("user_id","created_at");

package/drizzle/0006_chubby_gladiator.sql

@@ -0,0 +1,46 @@
+CREATE TABLE "notification_resource_parents" (
+	"child_target_type_id" text NOT NULL,
+	"child_resource_key" text NOT NULL,
+	"parent_target_type_id" text NOT NULL,
+	"parent_resource_key" text NOT NULL,
+	CONSTRAINT "notification_resource_parents_child_target_type_id_child_resource_key_parent_target_type_id_parent_resource_key_pk" PRIMARY KEY("child_target_type_id","child_resource_key","parent_target_type_id","parent_resource_key")
+);
+--> statement-breakpoint
+CREATE TABLE "notification_resources" (
+	"target_type_id" text NOT NULL,
+	"resource_key" text NOT NULL,
+	"display_label" text NOT NULL,
+	"upserted_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "notification_resources_target_type_id_resource_key_pk" PRIMARY KEY("target_type_id","resource_key")
+);
+--> statement-breakpoint
+CREATE TABLE "notification_targets" (
+	"target_type_id" text PRIMARY KEY NOT NULL,
+	"owner_plugin" text NOT NULL,
+	"resource_kind" text NOT NULL,
+	"parent_target_type_id" text,
+	"legacy_group_id_template" text,
+	"registered_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE TABLE "subscription_migrations" (
+	"spec_id" text NOT NULL,
+	"resource_key" text NOT NULL,
+	"migrated_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "subscription_migrations_spec_id_resource_key_pk" PRIMARY KEY("spec_id","resource_key")
+);
+--> statement-breakpoint
+CREATE TABLE "subscription_specs" (
+	"spec_id" text PRIMARY KEY NOT NULL,
+	"owner_plugin" text NOT NULL,
+	"local_id" text NOT NULL,
+	"target_type_id" text NOT NULL,
+	"display_title" text NOT NULL,
+	"display_description" text NOT NULL,
+	"display_icon_name" text,
+	"registered_at" timestamp DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+ALTER TABLE "notification_resources" ADD CONSTRAINT "notification_resources_target_type_id_notification_targets_target_type_id_fk" FOREIGN KEY ("target_type_id") REFERENCES "notification_targets"("target_type_id") ON DELETE cascade ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "subscription_specs" ADD CONSTRAINT "subscription_specs_target_type_id_notification_targets_target_type_id_fk" FOREIGN KEY ("target_type_id") REFERENCES "notification_targets"("target_type_id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "notification_resource_parents_child_idx" ON "notification_resource_parents" USING btree ("child_target_type_id","child_resource_key");

package/drizzle/meta/0005_snapshot.json

@@ -0,0 +1,237 @@
+{
+  "id": "487b48a4-723f-478c-ab7b-4512c095a7c4",
+  "prevId": "5899e448-f29a-46e2-b75d-51c7832c432b",
+  "version": "7",
+  "dialect": "postgresql",
+  "tables": {
+    "public.notification_groups": {
+      "name": "notification_groups",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "text",
+          "primaryKey": true,
+          "notNull": true
+        },
+        "name": {
+          "name": "name",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "description": {
+          "name": "description",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "owner_plugin": {
+          "name": "owner_plugin",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.notification_subscriptions": {
+      "name": "notification_subscriptions",
+      "schema": "",
+      "columns": {
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "group_id": {
+          "name": "group_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "subscribed_at": {
+          "name": "subscribed_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {},
+      "foreignKeys": {
+        "notification_subscriptions_group_id_notification_groups_id_fk": {
+          "name": "notification_subscriptions_group_id_notification_groups_id_fk",
+          "tableFrom": "notification_subscriptions",
+          "tableTo": "notification_groups",
+          "columnsFrom": [
+            "group_id"
+          ],
+          "columnsTo": [
+            "id"
+          ],
+          "onDelete": "cascade",
+          "onUpdate": "no action"
+        }
+      },
+      "compositePrimaryKeys": {
+        "notification_subscriptions_user_id_group_id_pk": {
+          "name": "notification_subscriptions_user_id_group_id_pk",
+          "columns": [
+            "user_id",
+            "group_id"
+          ]
+        }
+      },
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    },
+    "public.notifications": {
+      "name": "notifications",
+      "schema": "",
+      "columns": {
+        "id": {
+          "name": "id",
+          "type": "uuid",
+          "primaryKey": true,
+          "notNull": true,
+          "default": "gen_random_uuid()"
+        },
+        "user_id": {
+          "name": "user_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "title": {
+          "name": "title",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "body": {
+          "name": "body",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true
+        },
+        "action": {
+          "name": "action",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "importance": {
+          "name": "importance",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "'info'"
+        },
+        "is_read": {
+          "name": "is_read",
+          "type": "boolean",
+          "primaryKey": false,
+          "notNull": true,
+          "default": false
+        },
+        "group_id": {
+          "name": "group_id",
+          "type": "text",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "subjects": {
+          "name": "subjects",
+          "type": "jsonb",
+          "primaryKey": false,
+          "notNull": false
+        },
+        "created_at": {
+          "name": "created_at",
+          "type": "timestamp",
+          "primaryKey": false,
+          "notNull": true,
+          "default": "now()"
+        }
+      },
+      "indexes": {
+        "notifications_user_collapse_idx": {
+          "name": "notifications_user_collapse_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "group_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        },
+        "notifications_user_created_idx": {
+          "name": "notifications_user_created_idx",
+          "columns": [
+            {
+              "expression": "user_id",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            },
+            {
+              "expression": "created_at",
+              "isExpression": false,
+              "asc": true,
+              "nulls": "last"
+            }
+          ],
+          "isUnique": false,
+          "concurrently": false,
+          "method": "btree",
+          "with": {}
+        }
+      },
+      "foreignKeys": {},
+      "compositePrimaryKeys": {},
+      "uniqueConstraints": {},
+      "policies": {},
+      "checkConstraints": {},
+      "isRLSEnabled": false
+    }
+  },
+  "enums": {},
+  "schemas": {},
+  "sequences": {},
+  "roles": {},
+  "policies": {},
+  "views": {},
+  "_meta": {
+    "columns": {},
+    "schemas": {},
+    "tables": {}
+  }
+}