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. ' +

libs/api/tracker/presenters/src/lib/http/dto/requests.dto.ts

@@ -637,3 +637,39 @@ export class PublishReleaseDto {
   @IsBoolean()
   force = false;
 }
+
+// ---- Notifications ----------------------------------------------------------
+
+export class MyNotificationsQueryDto {
+  @ApiPropertyOptional({ default: false, description: 'Only unread ones' })
+  @IsOptional()
+  @Transform(toBoolean)
+  @IsBoolean()
+  unreadOnly = false;
+
+  @ApiPropertyOptional({ type: Number, default: 30, minimum: 1, maximum: 100 })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  @Max(100)
+  limit = 30;
+}
+
+export class MarkNotificationsReadDto {
+  @ApiPropertyOptional({
+    type: [String],
+    description: 'Omit to mark all of them',
+  })
+  @IsOptional()
+  @IsArray()
+  @ArrayMaxSize(200)
+  @IsString({ each: true })
+  ids?: string[];
+}
+
+export class NotificationSettingsDto {
+  @ApiProperty({ description: 'Copies by e-mail' })
+  @IsBoolean()
+  email!: boolean;
+}

libs/api/tracker/presenters/src/lib/http/dto/responses.dto.ts

@@ -2,6 +2,7 @@ import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import {
   IssueLinkType,
   IssuePriority,
+  NotificationKind,
   ProjectRole,
   ReleaseStatus,
   SETTING_COLORS,
@@ -354,3 +355,40 @@ export class ReleaseBurnupDto {
   scope!: number[];
   @ApiProperty({ type: [Number] }) done!: number[];
 }
+
+// ---- Notifications ----------------------------------------------------------
+
+export class NotificationDto {
+  @ApiProperty() id!: string;
+  @ApiProperty({ enum: NotificationKind, enumName: 'NotificationKind' })
+  kind!: NotificationKind;
+  @ApiProperty({ format: 'uuid' }) projectId!: string;
+  @ApiProperty({ example: 'WEB' }) projectKey!: string;
+  @ApiProperty({ type: String, nullable: true, format: 'uuid' })
+  issueId!: string | null;
+  @ApiProperty({ type: String, nullable: true, example: 'WEB-12' })
+  issueKey!: string | null;
+  @ApiProperty({ type: UserRefDto }) actor!: UserRefDto;
+  @ApiProperty({ example: 'Ana te asignó WEB-12: Login roto en Safari' })
+  summary!: string;
+  @ApiProperty({
+    type: String,
+    nullable: true,
+    format: 'date-time',
+    description: 'Null: unread',
+  })
+  readAt!: string | null;
+  @ApiProperty({ format: 'date-time' }) createdAt!: string;
+}
+
+export class MyNotificationsDto {
+  @ApiProperty({ type: [NotificationDto] }) items!: NotificationDto[];
+  @ApiProperty({ description: 'All my unread ones, not just these' })
+  unread!: number;
+}
+
+export class NotificationSettingsResponseDto {
+  @ApiProperty({ description: 'Copies by e-mail' }) email!: boolean;
+  @ApiProperty({ description: 'Whether this installation can send e-mail' })
+  emailAvailable!: boolean;
+}

libs/api/tracker/presenters/src/lib/http/notifications.controller.ts

@@ -0,0 +1,70 @@
+import { Body, Controller, Get, Post, Put, Query } from '@nestjs/common';
+import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { User } from '@task-stream/api/identity/domain';
+import {
+  ApiPireonAuth,
+  CurrentUser,
+} from '@task-stream/api/identity/presenters';
+import {
+  ApiCommandErrors,
+  ApiReadErrors,
+} from '@task-stream/api/shared/presenters';
+import { NotificationsService } from '@task-stream/api/tracker/application';
+import {
+  MarkNotificationsReadDto,
+  MyNotificationsQueryDto,
+  NotificationSettingsDto,
+} from './dto/requests.dto';
+import {
+  MyNotificationsDto,
+  NotificationSettingsResponseDto,
+} from './dto/responses.dto';
+
+/** REST adapter of the signed-in person's notifications. */
+@ApiTags('Users')
+@ApiPireonAuth()
+@Controller('me')
+export class NotificationsController {
+  constructor(private readonly notifications: NotificationsService) {}
+
+  @Get('notifications')
+  @ApiOperation({ summary: 'My notifications, newest first' })
+  @ApiOkResponse({ type: MyNotificationsDto })
+  @ApiReadErrors()
+  mine(@CurrentUser() me: User, @Query() query: MyNotificationsQueryDto) {
+    return this.notifications.mine(me.id, query);
+  }
+
+  @Post('notifications/read')
+  @ApiOperation({
+    summary: 'Mark notifications as read (all of them without `ids`)',
+  })
+  @ApiOkResponse({ description: 'Done' })
+  @ApiCommandErrors()
+  async markRead(
+    @CurrentUser() me: User,
+    @Body() body: MarkNotificationsReadDto,
+  ) {
+    await this.notifications.markRead(me.id, body.ids);
+    return { ok: true };
+  }
+
+  @Get('notification-settings')
+  @ApiOperation({ summary: 'Whether I get copies by e-mail' })
+  @ApiOkResponse({ type: NotificationSettingsResponseDto })
+  @ApiReadErrors()
+  settings(@CurrentUser() me: User) {
+    return this.notifications.settings(me.id);
+  }
+
+  @Put('notification-settings')
+  @ApiOperation({ summary: 'Turn e-mail copies on or off' })
+  @ApiOkResponse({ type: NotificationSettingsResponseDto })
+  @ApiCommandErrors()
+  updateSettings(
+    @CurrentUser() me: User,
+    @Body() body: NotificationSettingsDto,
+  ) {
+    return this.notifications.updateSettings(me.id, body);
+  }
+}

libs/api/tracker/presenters/src/lib/tracker-presenters.module.ts

@@ -3,6 +3,7 @@ import { ConfigService } from '@nestjs/config';
 import { MulterModule } from '@nestjs/platform-express';
 import './graphql/enums';
 import { CommentResolver } from './graphql/comment.resolver';
+import { NotificationResolver } from './graphql/notification.resolver';
 import { IssueResolver } from './graphql/issue.resolver';
 import { ProjectResolver } from './graphql/project.resolver';
 import { ReleaseResolver } from './graphql/release.resolver';
@@ -14,6 +15,7 @@ import { ExploreController } from './http/explore.controller';
 import { ProjectsController } from './http/projects.controller';
 import { Refs } from './http/refs';
 import { ReleasesController } from './http/releases.controller';
+import { NotificationsController } from './http/notifications.controller';
 
 /**
  * Driving adapters of the tracker context: GraphQL (queries, mutations,
@@ -42,6 +44,7 @@ import { ReleasesController } from './http/releases.controller';
     CommentsController,
     ReleasesController,
     ExploreController,
+    NotificationsController,
   ],
   providers: [
     Refs,
@@ -50,6 +53,7 @@ import { ReleasesController } from './http/releases.controller';
     CommentResolver,
     ReleaseResolver,
     SubscriptionResolver,
+    NotificationResolver,
   ],
 })
 export class TrackerPresentersModule {