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/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);
+  }
+}