feat: notifications in the app and, optionally, by e-mail

Derived from events and kept per person: whoever a ticket is assigned to,
whoever reports or works on it when it moves, fails QA or gets a comment,
and whoever joins a project. Never about what you did yourself, once per
event. They arrive live through a subscription to a bell in the header,
and are copied by e-mail to whoever turns it on when SMTP_URL is set.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

libs/api/tracker/presenters/src/lib/graphql/enums.ts

@@ -2,6 +2,7 @@ import { registerEnumType } from '@nestjs/graphql';
 import {
   IssueLinkType,
   IssuePriority,
+  NotificationKind,
   ProjectRole,
   ReleaseStatus,
   StatusCategory,
@@ -22,3 +23,7 @@ registerEnumType(IssueLinkType, { name: 'IssueLinkType' });
 registerEnumType(ProjectRole, { name: 'ProjectRole' });
 registerEnumType(ReleaseStatus, { name: 'ReleaseStatus' });
 registerEnumType(LinkDirection, { name: 'LinkDirection' });
+registerEnumType(NotificationKind, {
+  name: 'NotificationKind',
+  description: 'Why someone is told',
+});

libs/api/tracker/presenters/src/lib/graphql/notification.resolver.ts

@@ -0,0 +1,50 @@
+import { Args, ID, Int, Mutation, Query, Resolver } from '@nestjs/graphql';
+import { User } from '@task-stream/api/identity/domain';
+import { CurrentUser } from '@task-stream/api/identity/presenters';
+import { NotificationsService } from '@task-stream/api/tracker/application';
+import {
+  MyNotificationsGql,
+  NotificationGql,
+  NotificationSettingsGql,
+} from './types';
+
+/** The signed-in person's notifications. */
+@Resolver(() => NotificationGql)
+export class NotificationResolver {
+  constructor(private readonly notifications: NotificationsService) {}
+
+  @Query(() => MyNotificationsGql, {
+    description: 'My notifications, newest first, and how many are unread',
+  })
+  myNotifications(
+    @CurrentUser() me: User,
+    @Args('unreadOnly', { defaultValue: false }) unreadOnly: boolean,
+    @Args('limit', { type: () => Int, defaultValue: 30 }) limit: number,
+  ) {
+    return this.notifications.mine(me.id, { unreadOnly, limit });
+  }
+
+  @Query(() => NotificationSettingsGql)
+  notificationSettings(@CurrentUser() me: User) {
+    return this.notifications.settings(me.id);
+  }
+
+  @Mutation(() => Boolean, {
+    description: 'Mark these as read, or all of them when `ids` is omitted',
+  })
+  async markNotificationsRead(
+    @CurrentUser() me: User,
+    @Args('ids', { type: () => [ID], nullable: true }) ids?: string[] | null,
+  ) {
+    await this.notifications.markRead(me.id, ids);
+    return true;
+  }
+
+  @Mutation(() => NotificationSettingsGql)
+  updateNotificationSettings(
+    @CurrentUser() me: User,
+    @Args('email') email: boolean,
+  ) {
+    return this.notifications.updateSettings(me.id, { email });
+  }
+}

libs/api/tracker/presenters/src/lib/graphql/subscription.resolver.ts

@@ -1,11 +1,15 @@
 import { Args, ID, Resolver, Subscription } from '@nestjs/graphql';
 import { User } from '@task-stream/api/identity/domain';
 import { CurrentUser } from '@task-stream/api/identity/presenters';
-import { ChangesService } from '@task-stream/api/tracker/application';
+import {
+  ChangesService,
+  NotificationsService,
+} from '@task-stream/api/tracker/application';
 import {
   ActivityGql,
   CommentChangeGql,
   IssueChangeGql,
+  NotificationGql,
   ProjectChangeGql,
   ReleaseChangeGql,
 } from './types';
@@ -18,7 +22,10 @@ const asIs = { resolve: <T>(payload: T) => payload };
  */
 @Resolver()
 export class SubscriptionResolver {
-  constructor(private readonly changes: ChangesService) {}
+  constructor(
+    private readonly changes: ChangesService,
+    private readonly notifications: NotificationsService,
+  ) {}
 
   @Subscription(() => IssueChangeGql, {
     ...asIs,
@@ -74,4 +81,12 @@ export class SubscriptionResolver {
   myProjectsChanged(@CurrentUser() me: User) {
     return this.changes.watchMyProjects(me.id);
   }
+
+  @Subscription(() => NotificationGql, {
+    ...asIs,
+    description: 'My notifications, as they happen',
+  })
+  notificationAdded(@CurrentUser() me: User) {
+    return this.notifications.watch(me.id);
+  }
 }

libs/api/tracker/presenters/src/lib/graphql/types.ts

@@ -2,6 +2,7 @@ import { Field, Float, ID, Int, ObjectType } from '@nestjs/graphql';
 import {
   IssueLinkType,
   IssuePriority,
+  NotificationKind,
   ProjectRole,
   ReleaseStatus,
   StatusCategory,
@@ -242,6 +243,37 @@ export class ActivityGql {
   @Field() occurredAt!: string;
 }
 
+@ObjectType('Notification')
+export class NotificationGql {
+  @Field(() => ID) id!: string;
+  @Field(() => NotificationKind) kind!: NotificationKind;
+  @Field(() => ID) projectId!: string;
+  @Field() projectKey!: string;
+  @Field(() => ID, { nullable: true }) issueId!: string | null;
+  @Field(() => String, { nullable: true }) issueKey!: string | null;
+  @Field(() => UserRefGql) actor!: UserRefGql;
+  @Field() summary!: string;
+  @Field(() => String, { nullable: true, description: 'Null: unread' })
+  readAt!: string | null;
+  @Field() createdAt!: string;
+}
+
+@ObjectType('MyNotifications')
+export class MyNotificationsGql {
+  @Field(() => [NotificationGql]) items!: NotificationGql[];
+  @Field(() => Int, { description: 'All my unread ones, not just these' })
+  unread!: number;
+}
+
+@ObjectType('NotificationSettings')
+export class NotificationSettingsGql {
+  @Field({ description: 'Copies by e-mail' }) email!: boolean;
+  @Field({
+    description: 'Whether this installation can send e-mail at all',
+  })
+  emailAvailable!: boolean;
+}
+
 @ObjectType('CommandResult', {
   description:
     'Writes are acknowledged immediately; the read model catches up asynchronously. ' +