feat: a public notes page per release, for clients

On the releases page, «Página pública» (owners and admins) opens a
secret link to a page with the release's notes, readable without an
account, also for private projects: the notes written, or the draft
from its finished tickets while there are none (without repeating the
title the page already shows). The link can be copied, renewed (the old
one stops working) or withdrawn. Stored in Mongo (`release_note_shares`).

API: shareReleaseNotes / unshareReleaseNotes / releaseNotesShare,
publicReleaseNotes(token); GET/PUT/DELETE /api/releases/{id}/public-notes,
GET /api/shared/release-notes/{token}. Web: /notes/:token.

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

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

@@ -51,6 +51,8 @@ export * from './lib/ports/my-days.repository';
 export * from './lib/my-day.service';
 export * from './lib/commands/reviews';
 export * from './lib/commands/polls';
+export * from './lib/sharing/release-notes-shares';
+export * from './lib/ports/release-note-shares.repository';
 export * from './lib/tracker-application.module';
 export * from './lib/ports/presence.store';
 export * from './lib/presence.service';

libs/api/tracker/application/src/lib/ports/release-note-shares.repository.ts

@@ -0,0 +1,16 @@
+/** A release's public notes page: whoever has the link reads them. */
+export interface ReleaseNotesShare {
+  releaseId: string;
+  projectId: string;
+  /** Random and long; kept as it is so the link can be copied again. */
+  token: string;
+  createdAt: string;
+}
+
+export abstract class ReleaseNoteSharesRepository {
+  abstract findByRelease(releaseId: string): Promise<ReleaseNotesShare | null>;
+  abstract findByToken(token: string): Promise<ReleaseNotesShare | null>;
+  /** Replaces the release's link, if any. */
+  abstract save(share: ReleaseNotesShare): Promise<void>;
+  abstract remove(releaseId: string): Promise<void>;
+}

libs/api/tracker/application/src/lib/sharing.service.ts

@@ -11,8 +11,16 @@ import {
   ShareDashboardCommand,
   UnshareDashboardCommand,
 } from './sharing/dashboard-shares';
+import { ReleaseNotesShare } from './ports/release-note-shares.repository';
+import {
+  GetPublicReleaseNotesQuery,
+  GetReleaseNotesShareQuery,
+  PublicReleaseNotes,
+  ShareReleaseNotesCommand,
+  UnshareReleaseNotesCommand,
+} from './sharing/release-notes-shares';
 
-/** The project's dashboard for clients, behind a secret link. */
+/** The project's dashboard and its releases' notes, behind secret links. */
 @Injectable()
 export class SharingService {
   constructor(
@@ -48,6 +56,38 @@ export class SharingService {
     );
   }
 
+  /** A release's public notes link, if any (owners and admins). */
+  releaseNotesShare(
+    viewerId: string,
+    releaseId: string,
+  ): Promise<ReleaseNotesShare | null> {
+    return this.queryBus.execute(
+      new GetReleaseNotesShareQuery(viewerId, releaseId),
+    );
+  }
+
+  /** Turns a release's public notes on; `renew` makes a new secret. */
+  shareReleaseNotes(
+    actorId: string,
+    releaseId: string,
+    renew = false,
+  ): Promise<ReleaseNotesShare> {
+    return this.commands.execute(
+      new ShareReleaseNotesCommand(actorId, releaseId, renew),
+    );
+  }
+
+  unshareReleaseNotes(actorId: string, releaseId: string): Promise<void> {
+    return this.commands.execute(
+      new UnshareReleaseNotesCommand(actorId, releaseId),
+    );
+  }
+
+  /** A release's notes for anyone with the link, or null. */
+  publicReleaseNotes(token: string): Promise<PublicReleaseNotes | null> {
+    return this.queryBus.execute(new GetPublicReleaseNotesQuery(token));
+  }
+
   /** What a link shows now, or null if no project has it. */
   shared(token: string): Promise<SharedDashboardReadModel | null> {
     return this.queryBus.execute(new GetSharedDashboardQuery(token));

libs/api/tracker/application/src/lib/sharing/release-notes-shares.spec.ts

@@ -0,0 +1,160 @@
+import { CommandBus, CqrsModule, QueryBus } from '@nestjs/cqrs';
+import { Test } from '@nestjs/testing';
+import { ForbiddenError } from '@task-stream/api/shared/domain';
+import {
+  DEFAULT_PROJECT_SETTINGS,
+  IssueReadModel,
+  ReleaseReadModel,
+  ReleaseStatus,
+  StatusCategory,
+} from '@task-stream/api/tracker/domain';
+import { WriteAccess } from '../commands/write-access';
+import { FindIssuesRepository } from '../ports/find-issues.repository';
+import { FindProjectsRepository } from '../ports/find-projects.repository';
+import { FindReleasesRepository } from '../ports/find-releases.repository';
+import {
+  ReleaseNoteSharesRepository,
+  ReleaseNotesShare,
+} from '../ports/release-note-shares.repository';
+import {
+  GetPublicReleaseNotesQuery,
+  RELEASE_NOTES_SHARES,
+  ShareReleaseNotesCommand,
+  UnshareReleaseNotesCommand,
+} from './release-notes-shares';
+
+class InMemoryShares extends ReleaseNoteSharesRepository {
+  rows = new Map<string, ReleaseNotesShare>();
+  async findByRelease(releaseId: string) {
+    return this.rows.get(releaseId) ?? null;
+  }
+  async findByToken(token: string) {
+    return [...this.rows.values()].find((s) => s.token === token) ?? null;
+  }
+  async save(share: ReleaseNotesShare) {
+    this.rows.set(share.releaseId, share);
+  }
+  async remove(releaseId: string) {
+    this.rows.delete(releaseId);
+  }
+}
+
+const release: ReleaseReadModel = {
+  id: 'r1',
+  projectId: 'p1',
+  name: 'v2.0',
+  description: 'Pagos nuevos',
+  targetDate: '2026-11-15',
+  status: ReleaseStatus.PLANNED,
+  releasedAt: null,
+  notes: null,
+  createdAt: '',
+  version: 1,
+};
+
+async function setup() {
+  release.notes = null;
+  const shares = new InMemoryShares();
+  const moduleRef = await Test.createTestingModule({
+    imports: [CqrsModule.forRoot()],
+    providers: [
+      ...RELEASE_NOTES_SHARES,
+      { provide: ReleaseNoteSharesRepository, useValue: shares },
+      {
+        provide: FindReleasesRepository,
+        useValue: {
+          findById: async (id: string) => (id === 'r1' ? release : null),
+        },
+      },
+      {
+        provide: FindProjectsRepository,
+        useValue: {
+          findById: async () => ({
+            id: 'p1',
+            key: 'WEB',
+            name: 'Web',
+            settings: DEFAULT_PROJECT_SETTINGS,
+          }),
+        },
+      },
+      {
+        provide: FindIssuesRepository,
+        useValue: {
+          search: async () => ({
+            items: [
+              {
+                key: 'WEB-1',
+                number: 1,
+                title: 'Pago con Bizum',
+                type: 'FEATURE',
+                statusCategory: StatusCategory.DONE,
+              } as IssueReadModel,
+            ],
+            total: 1,
+          }),
+        },
+      },
+      {
+        provide: WriteAccess,
+        useValue: {
+          project: async () => {
+            const assertManages = (userId: string) => {
+              if (userId !== 'owner') throw new ForbiddenError('No');
+            };
+            return { assertManages, assertCanManage: assertManages };
+          },
+        },
+      },
+    ],
+  }).compile();
+  await moduleRef.init();
+  return {
+    commands: moduleRef.get(CommandBus),
+    queries: moduleRef.get(QueryBus),
+  };
+}
+
+describe("a release's public notes", () => {
+  it('opens for whoever manages the project, and keeps its link until renewed', async () => {
+    const { commands } = await setup();
+    await expect(
+      commands.execute(new ShareReleaseNotesCommand('dev', 'r1')),
+    ).rejects.toBeInstanceOf(ForbiddenError);
+    const first = await commands.execute(
+      new ShareReleaseNotesCommand('owner', 'r1'),
+    );
+    expect(first.token.length).toBeGreaterThan(30);
+    expect(
+      (await commands.execute(new ShareReleaseNotesCommand('owner', 'r1')))
+        .token,
+    ).toBe(first.token);
+    const renewed = await commands.execute(
+      new ShareReleaseNotesCommand('owner', 'r1', true),
+    );
+    expect(renewed.token).not.toBe(first.token);
+  });
+
+  it('shows the notes written, or the draft without repeating the title', async () => {
+    const { commands, queries } = await setup();
+    const { token } = await commands.execute(
+      new ShareReleaseNotesCommand('owner', 'r1'),
+    );
+    const drafted = await queries.execute(
+      new GetPublicReleaseNotesQuery(token),
+    );
+    expect(drafted).toMatchObject({ releaseName: 'v2.0', written: false });
+    expect(drafted?.notes).toContain('Pago con Bizum (WEB-1)');
+    expect(drafted?.notes).not.toContain('## v2.0');
+    expect(drafted?.notes).not.toContain('Pagos nuevos');
+
+    release.notes = '## Novedades\n- Bizum';
+    expect(
+      await queries.execute(new GetPublicReleaseNotesQuery(token)),
+    ).toMatchObject({ notes: '## Novedades\n- Bizum', written: true });
+
+    await commands.execute(new UnshareReleaseNotesCommand('owner', 'r1'));
+    expect(
+      await queries.execute(new GetPublicReleaseNotesQuery(token)),
+    ).toBeNull();
+  });
+});

libs/api/tracker/application/src/lib/sharing/release-notes-shares.ts

@@ -0,0 +1,235 @@
+import { randomBytes } from 'node:crypto';
+import {
+  Command,
+  CommandHandler,
+  ICommandHandler,
+  IQueryHandler,
+  Query,
+  QueryHandler,
+} from '@nestjs/cqrs';
+import { NotFoundError } from '@task-stream/api/shared/domain';
+import {
+  DEFAULT_PROJECT_SETTINGS,
+  ProjectWorkflow,
+  ReleaseStatus,
+} from '@task-stream/api/tracker/domain';
+import { WriteAccess } from '../commands/write-access';
+import { FindIssuesRepository } from '../ports/find-issues.repository';
+import { FindProjectsRepository } from '../ports/find-projects.repository';
+import { FindReleasesRepository } from '../ports/find-releases.repository';
+import {
+  ReleaseNoteSharesRepository,
+  ReleaseNotesShare,
+} from '../ports/release-note-shares.repository';
+import { draftReleaseNotes } from '../releases/release-notes';
+
+/*
+ * A release's notes as a public page, for clients: a secret link (also for
+ * private projects) that shows the notes written, or the ones drawn from
+ * its finished tickets while there are none.
+ */
+
+/** What the public page shows. */
+export interface PublicReleaseNotes {
+  projectName: string;
+  projectKey: string;
+  releaseName: string;
+  description: string | null;
+  status: ReleaseStatus;
+  targetDate: string | null;
+  releasedAt: string | null;
+  /** Markdown. */
+  notes: string;
+  /** False: drawn from its finished tickets (nobody wrote them yet). */
+  written: boolean;
+}
+
+/** Turns the link on; with `renew` (or the first time) a new secret. */
+export class ShareReleaseNotesCommand extends Command<ReleaseNotesShare> {
+  constructor(
+    public readonly actorId: string,
+    public readonly releaseId: string,
+    public readonly renew = false,
+  ) {
+    super();
+  }
+}
+
+export class UnshareReleaseNotesCommand extends Command<void> {
+  constructor(
+    public readonly actorId: string,
+    public readonly releaseId: string,
+  ) {
+    super();
+  }
+}
+
+/** The release's link, for whoever manages the project. */
+export class GetReleaseNotesShareQuery extends Query<ReleaseNotesShare | null> {
+  constructor(
+    public readonly viewerId: string,
+    public readonly releaseId: string,
+  ) {
+    super();
+  }
+}
+
+/** The page, for anyone with the link; null for an unknown one. */
+export class GetPublicReleaseNotesQuery extends Query<PublicReleaseNotes | null> {
+  constructor(public readonly token: string) {
+    super();
+  }
+}
+
+async function releaseOf(
+  findReleases: FindReleasesRepository,
+  releaseId: string,
+) {
+  const release = await findReleases.findById(releaseId);
+  if (!release) throw new NotFoundError('Release', releaseId);
+  return release;
+}
+
+@CommandHandler(ShareReleaseNotesCommand)
+export class ShareReleaseNotesCommandHandler
+  implements ICommandHandler<ShareReleaseNotesCommand>
+{
+  constructor(
+    private readonly shares: ReleaseNoteSharesRepository,
+    private readonly findReleases: FindReleasesRepository,
+    private readonly access: WriteAccess,
+  ) {}
+
+  async execute(command: ShareReleaseNotesCommand): Promise<ReleaseNotesShare> {
+    const release = await releaseOf(this.findReleases, command.releaseId);
+    (await this.access.project(release.projectId)).assertCanManage(
+      command.actorId,
+    );
+    const current = await this.shares.findByRelease(release.id);
+    if (current && !command.renew) return current;
+    const share: ReleaseNotesShare = {
+      releaseId: release.id,
+      projectId: release.projectId,
+      // 32 random bytes: nobody guesses it.
+      token: randomBytes(32).toString('base64url'),
+      createdAt: new Date().toISOString(),
+    };
+    await this.shares.save(share);
+    return share;
+  }
+}
+
+@CommandHandler(UnshareReleaseNotesCommand)
+export class UnshareReleaseNotesCommandHandler
+  implements ICommandHandler<UnshareReleaseNotesCommand>
+{
+  constructor(
+    private readonly shares: ReleaseNoteSharesRepository,
+    private readonly findReleases: FindReleasesRepository,
+    private readonly access: WriteAccess,
+  ) {}
+
+  async execute(command: UnshareReleaseNotesCommand): Promise<void> {
+    const release = await releaseOf(this.findReleases, command.releaseId);
+    (await this.access.project(release.projectId)).assertManages(
+      command.actorId,
+    );
+    await this.shares.remove(release.id);
+  }
+}
+
+@QueryHandler(GetReleaseNotesShareQuery)
+export class GetReleaseNotesShareQueryHandler
+  implements IQueryHandler<GetReleaseNotesShareQuery, ReleaseNotesShare | null>
+{
+  constructor(
+    private readonly shares: ReleaseNoteSharesRepository,
+    private readonly findReleases: FindReleasesRepository,
+    private readonly access: WriteAccess,
+  ) {}
+
+  async execute(
+    query: GetReleaseNotesShareQuery,
+  ): Promise<ReleaseNotesShare | null> {
+    const release = await releaseOf(this.findReleases, query.releaseId);
+    (await this.access.project(release.projectId)).assertManages(
+      query.viewerId,
+    );
+    return this.shares.findByRelease(release.id);
+  }
+}
+
+@QueryHandler(GetPublicReleaseNotesQuery)
+export class GetPublicReleaseNotesQueryHandler
+  implements
+    IQueryHandler<GetPublicReleaseNotesQuery, PublicReleaseNotes | null>
+{
+  constructor(
+    private readonly shares: ReleaseNoteSharesRepository,
+    private readonly findReleases: FindReleasesRepository,
+    private readonly findProjects: FindProjectsRepository,
+    private readonly findIssues: FindIssuesRepository,
+  ) {}
+
+  async execute(
+    query: GetPublicReleaseNotesQuery,
+  ): Promise<PublicReleaseNotes | null> {
+    const share = await this.shares.findByToken(query.token);
+    if (!share) return null;
+    const [release, project] = await Promise.all([
+      this.findReleases.findById(share.releaseId),
+      this.findProjects.findById(share.projectId),
+    ]);
+    // The release or the project was deleted: the link went with them.
+    if (!release || !project) return null;
+    const written = !!release.notes?.trim();
+    const notes = written
+      ? (release.notes as string)
+      : withoutHeading(
+          draftReleaseNotes({
+            release,
+            issues: (
+              await this.findIssues.search({
+                projectId: release.projectId,
+                releaseId: release.id,
+                limit: 500,
+                offset: 0,
+              })
+            ).items,
+            workflow: new ProjectWorkflow(
+              project.settings ?? DEFAULT_PROJECT_SETTINGS,
+            ),
+          }),
+          release.description,
+        );
+    return {
+      projectName: project.name,
+      projectKey: project.key,
+      releaseName: release.name,
+      description: release.description,
+      status: release.status,
+      targetDate: release.targetDate,
+      releasedAt: release.releasedAt,
+      notes,
+      written,
+    };
+  }
+}
+
+/**
+ * The draft without its title line (and description): the page shows the
+ * release's name, date and description above it already.
+ */
+function withoutHeading(draft: string, description: string | null): string {
+  let lines = draft.split('\n').slice(1);
+  if (description && lines[0] === '' && lines[1] === description)
+    lines = lines.slice(2);
+  return lines.join('\n').trim() + '\n';
+}
+
+export const RELEASE_NOTES_SHARES = [
+  ShareReleaseNotesCommandHandler,
+  UnshareReleaseNotesCommandHandler,
+  GetReleaseNotesShareQueryHandler,
+  GetPublicReleaseNotesQueryHandler,
+];

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

@@ -40,6 +40,7 @@ import { ALERT_HANDLERS } from './alerts/alerts';
 import { TREE_FOLLOWS } from './follows/tree-follows';
 import { ISSUE_REMINDERS } from './reminders/issue-reminders';
 import { MY_DAY } from './my-day/my-day';
+import { RELEASE_NOTES_SHARES } from './sharing/release-notes-shares';
 import { MyDayService } from './my-day.service';
 import { IssueRemindersService } from './issue-reminders.service';
 import { TreeFollowsService } from './tree-follows.service';
@@ -128,6 +129,7 @@ const SERVICES = [
     ...TREE_FOLLOWS,
     ...ISSUE_REMINDERS,
     ...MY_DAY,
+    ...RELEASE_NOTES_SHARES,
     ...GIT_HANDLERS,
     ...WEBHOOK_HANDLERS,
     ...TRANSFER_HANDLERS,