@checkstack/notification-backend 0.2.1 → 1.0.1

package/src/schema.ts

@@ -6,23 +6,54 @@ import {
   timestamp,
   jsonb,
   primaryKey,
+  index,
 } from "drizzle-orm/pg-core";
-import type { NotificationAction } from "@checkstack/notification-common";
+import type {
+  NotificationAction,
+  NotificationSubject,
+} from "@checkstack/notification-common";
 
 // User notifications table
-export const notifications = pgTable("notifications", {
-  id: uuid("id").primaryKey().defaultRandom(),
-  userId: text("user_id").notNull(), // No FK - cross-schema limitation
-  title: text("title").notNull(),
-  /** Notification body content (supports markdown) */
-  body: text("body").notNull(),
-  /** Single primary action button */
-  action: jsonb("action").$type<NotificationAction | null>(),
-  importance: text("importance").notNull().default("info"), // 'info' | 'warning' | 'critical'
-  isRead: boolean("is_read").notNull().default(false),
-  groupId: text("group_id"), // Namespaced: "pluginId.groupName"
-  createdAt: timestamp("created_at").defaultNow().notNull(),
-});
+export const notifications = pgTable(
+  "notifications",
+  {
+    id: uuid("id").primaryKey().defaultRandom(),
+    userId: text("user_id").notNull(), // No FK - cross-schema limitation
+    title: text("title").notNull(),
+    /** Notification body content (supports markdown) */
+    body: text("body").notNull(),
+    /** Single primary action button */
+    action: jsonb("action").$type<NotificationAction | null>(),
+    importance: text("importance").notNull().default("info"), // 'info' | 'warning' | 'critical'
+    isRead: boolean("is_read").notNull().default(false),
+    /**
+     * Collapse key shared by related notifications. Notifications with the
+     * same (userId, collapseKey) collapse into one card on the frontend.
+     * Examples: "incident.incident.<id>", "healthcheck.healthcheck.<id>".
+     * Distinct from `notification_groups.id` (which is a subscription target).
+     * Kept as `group_id` at the column level for backwards compatibility; the
+     * TypeScript field name reflects its true purpose.
+     */
+    collapseKey: text("group_id"),
+    /**
+     * Affected entities. Each renders as a chip (in-app) or a link (in
+     * notification strategies). When `action` is null, these are the only
+     * navigation paths; when present, they supplement the primary CTA.
+     */
+    subjects: jsonb("subjects").$type<NotificationSubject[] | null>(),
+    createdAt: timestamp("created_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    userCollapseIdx: index("notifications_user_collapse_idx").on(
+      t.userId,
+      t.collapseKey,
+    ),
+    userCreatedIdx: index("notifications_user_created_idx").on(
+      t.userId,
+      t.createdAt,
+    ),
+  }),
+);
 
 // Notification groups (created by plugins)
 // ID is namespaced: "pluginId.groupName"
@@ -52,3 +83,113 @@ export const notificationSubscriptions = pgTable(
 // Note: User notification preferences are now stored via ConfigService
 // using the user-pref.{userId}.{strategyId} pattern for automatic
 // secret encryption of OAuth tokens.
+
+/**
+ * Notification target type registry. Owned by a plugin (catalog owns
+ * `catalog.system` and `catalog.group`). The owner pushes resource
+ * lifecycle events to notification-backend; the backend uses this
+ * registry to route subscription specs to known resources and to walk
+ * parent inheritance during dispatch.
+ */
+export const notificationTargets = pgTable("notification_targets", {
+  targetTypeId: text("target_type_id").primaryKey(),
+  ownerPlugin: text("owner_plugin").notNull(),
+  resourceKind: text("resource_kind").notNull(),
+  parentTargetTypeId: text("parent_target_type_id"),
+  /**
+   * Template the backend substitutes `{resourceKey}` into to compute
+   * the legacy groupId for migration. Null means no legacy migration.
+   */
+  legacyGroupIdTemplate: text("legacy_group_id_template"),
+  registeredAt: timestamp("registered_at").defaultNow().notNull(),
+});
+
+/**
+ * Resources of a target type. Pushed by the target owner whenever a
+ * resource is created or renamed; removed on deletion. notification-
+ * backend keeps a notification group materialized for every
+ * (registered spec × resource) pair derived from this table.
+ */
+export const notificationResources = pgTable(
+  "notification_resources",
+  {
+    targetTypeId: text("target_type_id")
+      .notNull()
+      .references(() => notificationTargets.targetTypeId, {
+        onDelete: "cascade",
+      }),
+    resourceKey: text("resource_key").notNull(),
+    displayLabel: text("display_label").notNull(),
+    upsertedAt: timestamp("upserted_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.targetTypeId, t.resourceKey] }),
+  }),
+);
+
+/**
+ * Parent edges between resources. Populated by target owners via
+ * `setNotificationResourceParents` (catalog calls it on
+ * addSystemToGroup / removeSystemFromGroup / system create). Read at
+ * dispatch time to compute inherited group ids.
+ */
+export const notificationResourceParents = pgTable(
+  "notification_resource_parents",
+  {
+    childTargetTypeId: text("child_target_type_id").notNull(),
+    childResourceKey: text("child_resource_key").notNull(),
+    parentTargetTypeId: text("parent_target_type_id").notNull(),
+    parentResourceKey: text("parent_resource_key").notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({
+      columns: [
+        t.childTargetTypeId,
+        t.childResourceKey,
+        t.parentTargetTypeId,
+        t.parentResourceKey,
+      ],
+    }),
+    childIdx: index("notification_resource_parents_child_idx").on(
+      t.childTargetTypeId,
+      t.childResourceKey,
+    ),
+  }),
+);
+
+/**
+ * Subscription-spec registry. Every dispatch must reference a specId
+ * that exists here, owned by the calling plugin. notification-backend
+ * provisions one notification group per (spec × resource) pair where
+ * `resource.targetTypeId == spec.targetTypeId`.
+ */
+export const subscriptionSpecs = pgTable("subscription_specs", {
+  specId: text("spec_id").primaryKey(),
+  ownerPlugin: text("owner_plugin").notNull(),
+  localId: text("local_id").notNull(),
+  targetTypeId: text("target_type_id")
+    .notNull()
+    .references(() => notificationTargets.targetTypeId),
+  displayTitle: text("display_title").notNull(),
+  displayDescription: text("display_description").notNull(),
+  displayIconName: text("display_icon_name"),
+  registeredAt: timestamp("registered_at").defaultNow().notNull(),
+});
+
+/**
+ * Tracks which legacy notification groups have already been migrated
+ * for a given (spec × resource) pair. Set after the one-shot seeding
+ * runs so re-registering a spec doesn't re-seed (which would silently
+ * resubscribe users who deliberately unsubscribed).
+ */
+export const subscriptionMigrations = pgTable(
+  "subscription_migrations",
+  {
+    specId: text("spec_id").notNull(),
+    resourceKey: text("resource_key").notNull(),
+    migratedAt: timestamp("migrated_at").defaultNow().notNull(),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.specId, t.resourceKey] }),
+  }),
+);

package/src/subscription-engine.ts

@@ -0,0 +1,257 @@
+import { and, eq, inArray } from "drizzle-orm";
+import type { SafeDatabase } from "@checkstack/backend-api";
+import * as schema from "./schema";
+
+/**
+ * Server-local logic shared by every spec / target / resource / dispatch
+ * RPC. Centralizes the auto-provisioning, parent-edge lookup, and
+ * group-id derivation so plugins never compute groupIds themselves.
+ *
+ * Convention:
+ *   notification group id = `<spec.ownerPlugin>.<spec.localId>.<resourceKey>`
+ *
+ * That is the *only* way notification groups for spec subscriptions are
+ * named; there is no escape hatch.
+ */
+
+type Db = SafeDatabase<typeof schema>;
+
+export function deriveGroupId(opts: {
+  ownerPlugin: string;
+  localId: string;
+  resourceKey: string;
+}): string {
+  return `${opts.ownerPlugin}.${opts.localId}.${opts.resourceKey}`;
+}
+
+/**
+ * Materialize a single notification group for a (spec × resource) pair.
+ * Idempotent — relies on the existing `notification_groups` upsert.
+ */
+export async function ensureGroupForSpecAndResource(opts: {
+  db: Db;
+  spec: typeof schema.subscriptionSpecs.$inferSelect;
+  resource: typeof schema.notificationResources.$inferSelect;
+}): Promise<{ groupId: string; created: boolean }> {
+  const { db, spec, resource } = opts;
+  const groupId = deriveGroupId({
+    ownerPlugin: spec.ownerPlugin,
+    localId: spec.localId,
+    resourceKey: resource.resourceKey,
+  });
+
+  // Group naming follows `<DisplayLabel> <SpecTitle>` ("API Gateway
+  // Anomaly Detection") so audit lists and the bell render labels that
+  // make sense without context.
+  const groupName = `${resource.displayLabel} · ${spec.displayTitle}`;
+  const description = spec.displayDescription;
+
+  const existing = await db
+    .select({ id: schema.notificationGroups.id })
+    .from(schema.notificationGroups)
+    .where(eq(schema.notificationGroups.id, groupId))
+    .limit(1);
+  const created = existing.length === 0;
+
+  await db
+    .insert(schema.notificationGroups)
+    .values({
+      id: groupId,
+      name: groupName,
+      description,
+      ownerPlugin: spec.ownerPlugin,
+    })
+    .onConflictDoUpdate({
+      target: [schema.notificationGroups.id],
+      set: { name: groupName, description },
+    });
+
+  return { groupId, created };
+}
+
+export async function deleteGroupForSpecAndResource(opts: {
+  db: Db;
+  spec: { ownerPlugin: string; localId: string };
+  resourceKey: string;
+}): Promise<void> {
+  const { db, spec, resourceKey } = opts;
+  const groupId = deriveGroupId({
+    ownerPlugin: spec.ownerPlugin,
+    localId: spec.localId,
+    resourceKey,
+  });
+  await db
+    .delete(schema.notificationGroups)
+    .where(eq(schema.notificationGroups.id, groupId));
+}
+
+/**
+ * Provision groups for a newly-registered spec across every existing
+ * resource of its target. Also handles the one-shot legacy seeding when
+ * the target declared a legacy migration: subscribers of the legacy
+ * group are bulk-copied onto the new group, exactly once per
+ * (spec × resource), tracked in `subscription_migrations`.
+ */
+export async function provisionGroupsForSpec(opts: {
+  db: Db;
+  spec: typeof schema.subscriptionSpecs.$inferSelect;
+  legacyGroupIdFor?: (resourceKey: string) => string;
+}): Promise<void> {
+  const { db, spec, legacyGroupIdFor } = opts;
+
+  const resources = await db
+    .select()
+    .from(schema.notificationResources)
+    .where(eq(schema.notificationResources.targetTypeId, spec.targetTypeId));
+
+  for (const resource of resources) {
+    const { groupId } = await ensureGroupForSpecAndResource({
+      db,
+      spec,
+      resource,
+    });
+
+    if (!legacyGroupIdFor) continue;
+
+    const [migrated] = await db
+      .select()
+      .from(schema.subscriptionMigrations)
+      .where(
+        and(
+          eq(schema.subscriptionMigrations.specId, spec.specId),
+          eq(schema.subscriptionMigrations.resourceKey, resource.resourceKey),
+        ),
+      )
+      .limit(1);
+    if (migrated) continue;
+
+    const legacyGroupId = legacyGroupIdFor(resource.resourceKey);
+    const legacySubs = await db
+      .select({ userId: schema.notificationSubscriptions.userId })
+      .from(schema.notificationSubscriptions)
+      .where(eq(schema.notificationSubscriptions.groupId, legacyGroupId));
+
+    if (legacySubs.length > 0) {
+      await db
+        .insert(schema.notificationSubscriptions)
+        .values(
+          legacySubs.map((s) => ({ userId: s.userId, groupId })),
+        )
+        .onConflictDoNothing();
+    }
+
+    await db
+      .insert(schema.subscriptionMigrations)
+      .values({ specId: spec.specId, resourceKey: resource.resourceKey })
+      .onConflictDoNothing();
+  }
+}
+
+/**
+ * Provision groups for a newly-upserted resource across every spec
+ * registered against its target. Used both on first push and on rename
+ * (rename re-runs the upsert which refreshes group display labels).
+ */
+export async function provisionGroupsForResource(opts: {
+  db: Db;
+  targetTypeId: string;
+  resource: typeof schema.notificationResources.$inferSelect;
+}): Promise<void> {
+  const { db, targetTypeId, resource } = opts;
+  const specs = await db
+    .select()
+    .from(schema.subscriptionSpecs)
+    .where(eq(schema.subscriptionSpecs.targetTypeId, targetTypeId));
+  for (const spec of specs) {
+    await ensureGroupForSpecAndResource({ db, spec, resource });
+  }
+}
+
+/**
+ * Tear down all groups derived from a deleted resource across every
+ * matching spec. Returns how many were dropped.
+ */
+export async function teardownGroupsForResource(opts: {
+  db: Db;
+  targetTypeId: string;
+  resourceKey: string;
+}): Promise<number> {
+  const { db, targetTypeId, resourceKey } = opts;
+  const specs = await db
+    .select()
+    .from(schema.subscriptionSpecs)
+    .where(eq(schema.subscriptionSpecs.targetTypeId, targetTypeId));
+
+  if (specs.length === 0) return 0;
+
+  const groupIds = specs.map((spec) =>
+    deriveGroupId({
+      ownerPlugin: spec.ownerPlugin,
+      localId: spec.localId,
+      resourceKey,
+    }),
+  );
+  const deleted = await db
+    .delete(schema.notificationGroups)
+    .where(inArray(schema.notificationGroups.id, groupIds))
+    .returning({ id: schema.notificationGroups.id });
+  return deleted.length;
+}
+
+/**
+ * For dispatch: given a child (target, resourceKey), find every parent
+ * resource via `notification_resource_parents`, then map each parent to
+ * the same plugin's spec(s) whose `targetTypeId` equals the parent's
+ * target type. Inherited group ids are derived from those parent specs.
+ */
+export async function resolveInheritedGroupIds(opts: {
+  db: Db;
+  spec: typeof schema.subscriptionSpecs.$inferSelect;
+  resourceKey: string;
+}): Promise<string[]> {
+  const { db, spec, resourceKey } = opts;
+
+  const parents = await db
+    .select()
+    .from(schema.notificationResourceParents)
+    .where(
+      and(
+        eq(
+          schema.notificationResourceParents.childTargetTypeId,
+          spec.targetTypeId,
+        ),
+        eq(schema.notificationResourceParents.childResourceKey, resourceKey),
+      ),
+    );
+
+  if (parents.length === 0) return [];
+
+  const parentTargetTypeIds = [
+    ...new Set(parents.map((p) => p.parentTargetTypeId)),
+  ];
+
+  const parentSpecs = await db
+    .select()
+    .from(schema.subscriptionSpecs)
+    .where(
+      and(
+        eq(schema.subscriptionSpecs.ownerPlugin, spec.ownerPlugin),
+        inArray(schema.subscriptionSpecs.targetTypeId, parentTargetTypeIds),
+      ),
+    );
+
+  const out: string[] = [];
+  for (const parent of parents) {
+    for (const parentSpec of parentSpecs) {
+      if (parentSpec.targetTypeId !== parent.parentTargetTypeId) continue;
+      out.push(
+        deriveGroupId({
+          ownerPlugin: parentSpec.ownerPlugin,
+          localId: parentSpec.localId,
+          resourceKey: parent.parentResourceKey,
+        }),
+      );
+    }
+  }
+  return out;
+}

package/tsconfig.json

@@ -2,5 +2,40 @@
   "extends": "@checkstack/tsconfig/backend.json",
   "include": [
     "src"
+  ],
+  "references": [
+    {
+      "path": "../auth-backend"
+    },
+    {
+      "path": "../auth-common"
+    },
+    {
+      "path": "../backend-api"
+    },
+    {
+      "path": "../cache-api"
+    },
+    {
+      "path": "../cache-utils"
+    },
+    {
+      "path": "../common"
+    },
+    {
+      "path": "../drizzle-helper"
+    },
+    {
+      "path": "../notification-common"
+    },
+    {
+      "path": "../queue-api"
+    },
+    {
+      "path": "../signal-common"
+    },
+    {
+      "path": "../test-utils-backend"
+    }
   ]
-}
+}