feat: due-date reminders

Every hour the API reminds whoever has a ticket, and whoever follows it,
the day before its due date, on the day and once when it is overdue, in
the app and by e-mail for those who asked. Cards on the board flag what
is due soon or late.

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

libs/api/tracker/application/src/lib/notifications/index.ts

@@ -1,3 +1,4 @@
 export * from './notifier';
 export * from './notifications.queries';
 export * from './notifications.commands';
+export * from './reminders';

libs/api/tracker/application/src/lib/notifications/notifier.ts

@@ -60,9 +60,8 @@ export class Notifier {
         ? { id: SYSTEM_ACTOR_ID, name: SYSTEM_ACTOR_NAME }
         : refs.of(event.actorId);
 
-    const delivered: NotificationReadModel[] = [];
-    for (const draft of wanted) {
-      const notification: NotificationReadModel = {
+    await this.send(
+      wanted.map((draft) => ({
         id: `${event.aggregateId}:${versionOf(event)}:${draft.userId}`,
         userId: draft.userId,
         kind: draft.kind,
@@ -71,13 +70,22 @@ export class Notifier {
         summary: draft.summary,
         readAt: null,
         createdAt: event.occurredAt,
-      };
+      })),
+    );
+  }
+
+  /**
+   * Stores, pushes and e-mails ready-made notifications. Their id makes them
+   * idempotent: one that is already there is not sent again.
+   */
+  async send(notifications: NotificationReadModel[]): Promise<void> {
+    const delivered: NotificationReadModel[] = [];
+    for (const notification of notifications) {
       // Delivered again (at-least-once): already told, nothing to repeat.
       if (!(await this.notifications.insert(notification))) continue;
       await this.changeFeed.publishNotification(notification);
       delivered.push(notification);
     }
-
     if (this.mailer.enabled && delivered.length) {
       await this.email(delivered);
     }

libs/api/tracker/application/src/lib/notifications/reminders.spec.ts

@@ -0,0 +1,43 @@
+import {
+  IssueReadModel,
+  NotificationKind,
+} from '@task-stream/api/tracker/domain';
+import { dueStage, nextDay, remindersFor } from './reminders';
+
+const issue = (id: string, dueDate: string, watchers: string[] = []) =>
+  ({
+    id,
+    key: `WEB-${id}`,
+    title: `T${id}`,
+    projectId: 'p',
+    projectKey: 'WEB',
+    dueDate,
+    assignee: { id: 'ana', name: 'Ana' },
+    watchers: watchers.map((w) => ({ id: w, name: w })),
+  }) as IssueReadModel;
+
+describe('due reminders', () => {
+  it('tells the stage of a due date', () => {
+    expect(nextDay('2026-12-31')).toBe('2027-01-01');
+    expect(dueStage('2026-10-09', '2026-10-08')).toBe('tomorrow');
+    expect(dueStage('2026-10-08', '2026-10-08')).toBe('today');
+    expect(dueStage('2026-10-01', '2026-10-08')).toBe('overdue');
+    expect(dueStage('2026-10-20', '2026-10-08')).toBeNull();
+  });
+
+  it('reminds whoever has it and whoever follows it, once per stage', () => {
+    const reminders = remindersFor(
+      [issue('1', '2026-10-08', ['ana', 'bob']), issue('2', '2026-10-30')],
+      '2026-10-08',
+      '2026-10-08T07:00:00Z',
+    );
+    expect(reminders.map((r) => [r.userId, r.summary])).toEqual([
+      ['ana', 'WEB-1 vence hoy: T1'],
+      ['bob', 'WEB-1 vence hoy: T1'],
+    ]);
+    expect(reminders[0]).toMatchObject({
+      kind: NotificationKind.REMINDER,
+      id: 'reminder:1:2026-10-08:today:ana',
+    });
+  });
+});

libs/api/tracker/application/src/lib/notifications/reminders.ts

@@ -0,0 +1,111 @@
+import { Command, CommandHandler, ICommandHandler } from '@nestjs/cqrs';
+import {
+  IssueReadModel,
+  NotificationKind,
+  NotificationReadModel,
+  SYSTEM_ACTOR_ID,
+  SYSTEM_ACTOR_NAME,
+} from '@task-stream/api/tracker/domain';
+import { FindIssuesRepository } from '../ports/find-issues.repository';
+import { Notifier } from './notifier';
+
+/** Where a due date stands, from the reminder's point of view. */
+export type DueStage = 'tomorrow' | 'today' | 'overdue';
+
+const DAY = 86_400_000;
+
+/** `YYYY-MM-DD` one day after `day`. */
+export function nextDay(day: string): string {
+  return new Date(Date.parse(`${day}T00:00:00Z`) + DAY)
+    .toISOString()
+    .slice(0, 10);
+}
+
+export function dueStage(dueDate: string, today: string): DueStage | null {
+  const due = dueDate.slice(0, 10);
+  if (due < today) return 'overdue';
+  if (due === today) return 'today';
+  return due === nextDay(today) ? 'tomorrow' : null;
+}
+
+const day = (iso: string) =>
+  new Date(`${iso.slice(0, 10)}T00:00:00Z`).toLocaleDateString('es', {
+    day: 'numeric',
+    month: 'short',
+    timeZone: 'UTC',
+  });
+
+/**
+ * One reminder per ticket, due date and stage — the day before, on the day,
+ * and once when it is overdue — for whoever has it and whoever follows it.
+ * Ids make it idempotent: running it every hour, on every instance, is fine.
+ */
+export function remindersFor(
+  issues: IssueReadModel[],
+  today: string,
+  now: string,
+): NotificationReadModel[] {
+  const out: NotificationReadModel[] = [];
+  for (const issue of issues) {
+    if (!issue.dueDate) continue;
+    const stage = dueStage(issue.dueDate, today);
+    if (!stage) continue;
+    const summary =
+      stage === 'tomorrow'
+        ? `${issue.key} vence mañana: ${issue.title}`
+        : stage === 'today'
+          ? `${issue.key} vence hoy: ${issue.title}`
+          : `${issue.key} venció el ${day(issue.dueDate)} y sigue abierto: ${issue.title}`;
+    const people = new Set(
+      [issue.assignee?.id, ...(issue.watchers ?? []).map((w) => w.id)].filter(
+        (id): id is string => !!id,
+      ),
+    );
+    for (const userId of people)
+      out.push({
+        id: `reminder:${issue.id}:${issue.dueDate.slice(0, 10)}:${stage}:${userId}`,
+        userId,
+        kind: NotificationKind.REMINDER,
+        projectId: issue.projectId,
+        projectKey: issue.projectKey,
+        issueId: issue.id,
+        issueKey: issue.key,
+        actor: { id: SYSTEM_ACTOR_ID, name: SYSTEM_ACTOR_NAME },
+        summary,
+        readAt: null,
+        createdAt: now,
+      });
+  }
+  return out;
+}
+
+/** Scheduler only: tells people about tickets due tomorrow, today or overdue. */
+export class SendDueRemindersCommand extends Command<number> {
+  constructor(
+    /** `YYYY-MM-DD` in the installation's time zone. */
+    public readonly today: string,
+  ) {
+    super();
+  }
+}
+
+@CommandHandler(SendDueRemindersCommand)
+export class SendDueRemindersCommandHandler
+  implements ICommandHandler<SendDueRemindersCommand>
+{
+  constructor(
+    private readonly findIssues: FindIssuesRepository,
+    private readonly notifier: Notifier,
+  ) {}
+
+  async execute(command: SendDueRemindersCommand): Promise<number> {
+    const due = await this.findIssues.findDueBy(nextDay(command.today));
+    const reminders = remindersFor(
+      due,
+      command.today,
+      new Date().toISOString(),
+    );
+    await this.notifier.send(reminders);
+    return reminders.length;
+  }
+}

libs/api/tracker/application/src/lib/ports/find-issues.repository.ts

@@ -64,6 +64,8 @@ export abstract class FindIssuesRepository {
   abstract stats(projectId: string): Promise<ProjectStatsReadModel>;
   /** Open tickets (TODO, IN_PROGRESS or QA category) assigned to someone, in any project. */
   abstract findOpenAssignedTo(userId: string): Promise<IssueReadModel[]>;
+  /** Unfinished tickets with someone on them, due on or before `day` (YYYY-MM-DD). */
+  abstract findDueBy(day: string): Promise<IssueReadModel[]>;
   /** Every ticket of a project (statistics). */
   abstract findByProject(projectId: string): Promise<IssueReadModel[]>;
   /** Top-level tickets with others hanging from them, by key. */

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

@@ -30,6 +30,7 @@ import {
 } from './notifications/notifications.commands';
 
 import { SAVED_FILTERS } from './saved-filters/saved-filters';
+import { SendDueRemindersCommandHandler } from './notifications/reminders';
 import { SavedFiltersService } from './saved-filters.service';
 import { SprintsService } from './sprints.service';
 import { GitService } from './git.service';
@@ -49,6 +50,7 @@ const NOTIFICATIONS = [
   GetMyNotificationSettingsQueryHandler,
   MarkNotificationsReadCommandHandler,
   UpdateNotificationSettingsCommandHandler,
+  SendDueRemindersCommandHandler,
 ];
 
 const SERVICES = [

libs/api/tracker/infrastructure/src/lib/mongo/find.repositories.ts

@@ -238,6 +238,18 @@ export class MongoFindIssuesRepository extends FindIssuesRepository {
     return docs.map(issueFromDoc);
   }
 
+  async findDueBy(day: string): Promise<IssueReadModel[]> {
+    const docs = await this.issues
+      .find({
+        dueDate: { $ne: null, $lte: `${day}\uffff` },
+        statusCategory: { $nin: FINISHED },
+        $or: [{ assignee: { $ne: null } }, { 'watchers.0': { $exists: true } }],
+      })
+      .limit(5000)
+      .lean<IssueDoc[]>();
+    return docs.map(issueFromDoc);
+  }
+
   async findByProject(projectId: string): Promise<IssueReadModel[]> {
     const docs = await this.issues.find({ projectId }).lean<IssueDoc[]>();
     return docs.map(issueFromDoc);

libs/api/tracker/infrastructure/src/lib/notifications/reminder.scheduler.spec.ts

@@ -0,0 +1,9 @@
+import { dayIn } from './reminder.scheduler';
+
+describe('reminder scheduler', () => {
+  it("knows the installation's date, not UTC's", () => {
+    const lateNight = new Date('2026-10-08T23:30:00Z');
+    expect(dayIn(lateNight, 'UTC')).toBe('2026-10-08');
+    expect(dayIn(lateNight, 'Europe/Madrid')).toBe('2026-10-09');
+  });
+});

libs/api/tracker/infrastructure/src/lib/notifications/reminder.scheduler.ts

@@ -0,0 +1,69 @@
+import {
+  Injectable,
+  Logger,
+  OnApplicationBootstrap,
+  OnApplicationShutdown,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { CommandBus } from '@nestjs/cqrs';
+import { SendDueRemindersCommand } from '@task-stream/api/tracker/application';
+
+const HOUR = 3_600_000;
+
+/** `YYYY-MM-DD` of `date` in `timeZone`. */
+export function dayIn(date: Date, timeZone: string): string {
+  return new Intl.DateTimeFormat('sv-SE', {
+    timeZone,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  }).format(date);
+}
+
+/**
+ * Sends due-date reminders a minute after start and then every hour, in the
+ * installation's time zone (REMINDERS_TIMEZONE). Reminders are idempotent, so
+ * several instances running this at once only repeat lookups.
+ * REMINDERS_ENABLED=false turns it off.
+ */
+@Injectable()
+export class ReminderScheduler
+  implements OnApplicationBootstrap, OnApplicationShutdown
+{
+  private readonly logger = new Logger(ReminderScheduler.name);
+  private timers: ReturnType<typeof setTimeout>[] = [];
+
+  constructor(
+    private readonly commandBus: CommandBus,
+    private readonly config: ConfigService,
+  ) {}
+
+  onApplicationBootstrap(): void {
+    if (String(this.config.get('REMINDERS_ENABLED') ?? 'true') === 'false')
+      return;
+    const first = setTimeout(() => void this.run(), 60_000);
+    const every = setInterval(() => void this.run(), HOUR);
+    first.unref?.();
+    every.unref?.();
+    this.timers = [first, every];
+  }
+
+  onApplicationShutdown(): void {
+    this.timers.forEach((timer) => clearTimeout(timer));
+  }
+
+  private async run(): Promise<void> {
+    const timeZone =
+      this.config.get<string>('REMINDERS_TIMEZONE') || 'Europe/Madrid';
+    try {
+      const sent: number = await this.commandBus.execute(
+        new SendDueRemindersCommand(dayIn(new Date(), timeZone)),
+      );
+      if (sent) this.logger.log(`Due-date reminders checked (${sent})`);
+    } catch (error) {
+      this.logger.warn(
+        `Due-date reminders failed: ${(error as Error).message}`,
+      );
+    }
+  }
+}

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

@@ -53,6 +53,7 @@ import {
 } from './mongo/upsert-materialized.repositories';
 import { StatusCategoryBackfill } from './mongo/status-category.backfill';
 import { RankBackfill } from './mongo/rank.backfill';
+import { ReminderScheduler } from './notifications/reminder.scheduler';
 import { LOOKUP_ENTITIES } from './postgres/lookup.entities';
 import {
   PostgresIssueNumbersRepository,
@@ -153,7 +154,12 @@ const PORTS = [
     TypeOrmModule.forFeature(LOOKUP_ENTITIES),
     MongooseModule.forFeature(READ_MODEL_SCHEMAS),
   ],
-  providers: [...PORTS, StatusCategoryBackfill, RankBackfill],
+  providers: [
+    ...PORTS,
+    StatusCategoryBackfill,
+    RankBackfill,
+    ReminderScheduler,
+  ],
   exports: PORTS.map((port) => port.provide),
 })
 export class TrackerInfrastructureModule {}