@ftisindia/create-app 0.1.4 → 0.1.6

package/template/src/modules/organisations/presentation/organisations.controller.ts

@@ -1,12 +1,22 @@
-import { Body, Controller, Post, UseGuards } from '@nestjs/common';
-import { ApiBearerAuth, ApiCreatedResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { Body, Controller, Get, Post, Query, UseGuards } from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiTags,
+} from '@nestjs/swagger';
+import { PaginationQueryDto } from '../../../common/dto/pagination-query.dto';
 import { ApiErrorResponses } from '../../../common/swagger/api-error-responses';
 import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
 import { CurrentUser } from '../../auth/presentation/current-user.decorator';
 import { AuthenticatedUser } from '../../auth/types/authenticated-user';
 import { OrganisationsService } from '../application/services/organisations.service';
 import { CreateOrganisationDto } from '../dto/create-organisation.dto';
-import { CreateOrganisationResponseDto } from '../dto/organisation-response.dto';
+import {
+  CreateOrganisationResponseDto,
+  MyOrganisationListResponseDto,
+} from '../dto/organisation-response.dto';
 
 @ApiTags('Organisations')
 @ApiBearerAuth()
@@ -14,6 +24,18 @@ import { CreateOrganisationResponseDto } from '../dto/organisation-response.dto'
 export class OrganisationsController {
   constructor(private readonly organisationsService: OrganisationsService) {}
 
+  @Get('mine')
+  @UseGuards(JwtAuthGuard)
+  @ApiOperation({ summary: 'List active organisations for the current user.' })
+  @ApiOkResponse({
+    description: 'Current user organisations.',
+    type: MyOrganisationListResponseDto,
+  })
+  @ApiErrorResponses(400, 401)
+  mine(@CurrentUser() user: AuthenticatedUser, @Query() query: PaginationQueryDto) {
+    return this.organisationsService.listMine(user, query);
+  }
+
   @Post()
   @UseGuards(JwtAuthGuard)
   @ApiOperation({ summary: 'Create an organisation for the current user.' })

package/template/src/modules/reports/application/services/reports-actions.service.ts

@@ -0,0 +1,54 @@
+import { Injectable } from '@nestjs/common';
+import { ReportActionService } from '@ftisindia/report-builder';
+import type { Selection } from '@ftisindia/report-builder';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { ExecuteActionDto } from '../../dto/execute-action.dto';
+import { PrepareActionDto } from '../../dto/prepare-action.dto';
+import { RequestReportsContext } from '../../infrastructure/request-reports-context';
+import { withReportsErrorMapping } from './reports-error.mapper';
+
+/**
+ * Thin HTTP-facing wrapper over the engine's ReportActionService. The §6.3
+ * protocol — token verification, drift detection, keyset batching, the
+ * idempotency ledger — and the per-action permission checks (§6.1's
+ * execute-time layer) all live in the engine.
+ */
+@Injectable()
+export class ReportsActionsService {
+  constructor(
+    private readonly engine: ReportActionService,
+    private readonly reportsContext: RequestReportsContext,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async prepare(orgId: string, key: string, actionName: string, dto: PrepareActionDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() =>
+      this.engine.prepare(
+        orgId,
+        key,
+        actionName,
+        dto.selection as unknown as Selection,
+        this.reportsContext,
+      ),
+    );
+  }
+
+  async execute(orgId: string, key: string, actionName: string, dto: ExecuteActionDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() =>
+      this.engine.execute(
+        orgId,
+        key,
+        actionName,
+        {
+          selection: dto.selection as unknown as Selection | undefined,
+          actionToken: dto.actionToken,
+          input: dto.input,
+          idempotencyKey: dto.idempotencyKey,
+        },
+        this.reportsContext,
+      ),
+    );
+  }
+}

package/template/src/modules/reports/application/services/reports-definitions.service.ts

@@ -0,0 +1,66 @@
+import { Injectable } from '@nestjs/common';
+import { ReportDefinitionService } from '@ftisindia/report-builder';
+import { resolvePageLimit, toPage } from '../../../../common/dto/pagination-query.dto';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { CreateReportDefinitionDto } from '../../dto/create-report-definition.dto';
+import { ListReportsQueryDto } from '../../dto/list-reports-query.dto';
+import { UpdateReportDefinitionDto } from '../../dto/update-report-definition.dto';
+import { RequestReportsContext } from '../../infrastructure/request-reports-context';
+import { withReportsErrorMapping } from './reports-error.mapper';
+
+/**
+ * Thin HTTP-facing wrapper over the engine's ReportDefinitionService:
+ * org-scope assertion first, engine call through the ReportsContext seam,
+ * engine-typed errors mapped onto the app's HTTP envelope. No business logic
+ * lives here — save/publish linting, tier gates, and state transitions all
+ * belong to the engine (design §2/§8/§10).
+ */
+@Injectable()
+export class ReportsDefinitionsService {
+  constructor(
+    private readonly engine: ReportDefinitionService,
+    private readonly reportsContext: RequestReportsContext,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async list(orgId: string, query: ListReportsQueryDto) {
+    this.requestContext.assertOrgScope(orgId);
+    const limit = resolvePageLimit(query.limit);
+
+    const records = await withReportsErrorMapping(() =>
+      this.engine.list(orgId, this.reportsContext, {
+        status: query.status,
+        cursor: query.cursor,
+        limit: limit + 1,
+      }),
+    );
+
+    return toPage(records, limit);
+  }
+
+  async create(orgId: string, dto: CreateReportDefinitionDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() => this.engine.create(orgId, dto, this.reportsContext));
+  }
+
+  async getLatest(orgId: string, key: string) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() => this.engine.get(orgId, key, this.reportsContext));
+  }
+
+  async update(orgId: string, key: string, dto: UpdateReportDefinitionDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() => this.engine.update(orgId, key, dto, this.reportsContext));
+  }
+
+  async publish(orgId: string, key: string) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() => this.engine.publish(orgId, key, this.reportsContext));
+  }
+
+  async archive(orgId: string, key: string) {
+    this.requestContext.assertOrgScope(orgId);
+    await withReportsErrorMapping(() => this.engine.archive(orgId, key, this.reportsContext));
+    return { archived: true };
+  }
+}

package/template/src/modules/reports/application/services/reports-error.mapper.ts

@@ -0,0 +1,97 @@
+import {
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+  GoneException,
+  NotFoundException,
+  RequestTimeoutException,
+  UnauthorizedException,
+  UnprocessableEntityException,
+} from '@nestjs/common';
+import {
+  ReportAuthzDeniedError,
+  ReportConflictError,
+  ReportCursorError,
+  ReportDriftError,
+  ReportExportError,
+  ReportLintError,
+  ReportNotFoundError,
+  ReportQueryBudgetError,
+  ReportSpecError,
+  ReportStateError,
+  ReportTokenError,
+} from '@ftisindia/report-builder';
+import { Prisma } from '@prisma/client';
+
+/**
+ * Maps the engine's typed errors (ecosystem guide §2.1, report design §10)
+ * onto the app's HTTP error envelope. Object bodies survive the global
+ * HttpExceptionFilter, which lifts every non-message key into `error.details`
+ * — so 422 lint responses carry the engine's `issues` array (plus the §8
+ * `suggestionSql` migration snippet) verbatim, and 409 drift responses carry
+ * both counts so the client can re-confirm with fresh facts.
+ */
+export function mapReportsError(error: unknown): never {
+  if (error instanceof ReportSpecError || error instanceof ReportCursorError) {
+    throw new BadRequestException({ message: error.message, code: error.code });
+  }
+
+  if (error instanceof ReportTokenError) {
+    if (error.expired) {
+      throw new GoneException(error.message);
+    }
+    throw new UnauthorizedException(error.message);
+  }
+
+  if (error instanceof ReportLintError) {
+    throw new UnprocessableEntityException({
+      message: error.message,
+      issues: error.issues,
+      ...(error.suggestionSql === undefined ? {} : { suggestionSql: error.suggestionSql }),
+    });
+  }
+
+  if (error instanceof ReportDriftError) {
+    throw new ConflictException({
+      message: error.message,
+      expectedCount: error.expectedCount,
+      currentCount: error.currentCount,
+      code: 'REPORTS_SELECTION_DRIFT',
+    });
+  }
+
+  if (error instanceof ReportAuthzDeniedError) {
+    throw new ForbiddenException(error.message);
+  }
+
+  if (error instanceof ReportNotFoundError) {
+    throw new NotFoundException(error.message);
+  }
+
+  if (error instanceof ReportConflictError || error instanceof ReportStateError) {
+    throw new ConflictException(error.message);
+  }
+
+  if (error instanceof ReportQueryBudgetError) {
+    throw new RequestTimeoutException(error.message);
+  }
+
+  if (error instanceof ReportExportError) {
+    throw new UnprocessableEntityException(error.message);
+  }
+
+  if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002') {
+    throw new ConflictException('A report record with these unique fields already exists.');
+  }
+
+  throw error;
+}
+
+/** Awaits an engine call and maps any engine-typed failure onto HTTP errors. */
+export async function withReportsErrorMapping<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    mapReportsError(error);
+  }
+}

package/template/src/modules/reports/application/services/reports-export-dispatcher.service.ts

@@ -0,0 +1,124 @@
+import {
+  Injectable,
+  Logger,
+  OnApplicationBootstrap,
+  OnModuleDestroy,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { ReportExportService } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { RequestReportsContext } from '../../infrastructure/request-reports-context';
+
+/**
+ * Reports-OWNED async export worker (report design §9). Instead of riding the
+ * forms transactional outbox, it polls the engine's own `ReportExportJob`
+ * table for PENDING rows — so the reports module needs no FormsModule. Each
+ * job is claimed atomically (PENDING → RUNNING) to prevent double-processing,
+ * then run inside a restored worker request context (source: 'worker', orgId,
+ * userId) exactly as the forms dispatcher restores context for its handlers.
+ *
+ * The engine's ReportExportService.runJob streams from one REPEATABLE READ
+ * snapshot into the reports export storage and marks the row DONE/FAILED.
+ */
+@Injectable()
+export class ReportsExportDispatcherService implements OnApplicationBootstrap, OnModuleDestroy {
+  private readonly logger = new Logger('ReportsExportWorker');
+  private timer?: NodeJS.Timeout;
+  private ticking = false;
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly prisma: PrismaService,
+    private readonly exports: ReportExportService,
+    private readonly requestContext: RequestContextService,
+    private readonly reportsContext: RequestReportsContext,
+  ) {}
+
+  onApplicationBootstrap(): void {
+    if (this.config.get<boolean>('reports.exportWorkerEnabled') === false) {
+      return;
+    }
+    const pollMs = this.config.get<number>('reports.exportPollMs') ?? 5000;
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, pollMs);
+    this.timer.unref?.();
+  }
+
+  onModuleDestroy(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+    }
+  }
+
+  /** One poll cycle — exposed for tests / manual draining. */
+  async runOnce(batchSize = 10): Promise<{ claimed: number; done: number; failed: number }> {
+    const pending = await this.prisma.reportExportJob.findMany({
+      where: { status: 'PENDING' },
+      orderBy: { createdAt: 'asc' },
+      take: batchSize,
+      select: { id: true, orgId: true, requestedBy: true },
+    });
+
+    let claimed = 0;
+    let done = 0;
+    let failed = 0;
+    for (const job of pending) {
+      // Atomic claim: only the worker that flips PENDING → RUNNING runs it.
+      const claim = await this.prisma.reportExportJob.updateMany({
+        where: { id: job.id, orgId: job.orgId, status: 'PENDING' },
+        data: { status: 'RUNNING' },
+      });
+      if (claim.count !== 1) {
+        continue;
+      }
+      claimed += 1;
+
+      const outcome = await this.requestContext.run(
+        {
+          source: 'worker',
+          orgId: job.orgId,
+          userId: job.requestedBy,
+        },
+        async () => {
+          try {
+            await this.exports.runJob(job.orgId, job.id, this.reportsContext);
+            return 'done' as const;
+          } catch (error) {
+            this.logger.error(
+              `Export job ${job.id} failed.`,
+              error instanceof Error ? error.stack : String(error),
+            );
+            return 'failed' as const;
+          }
+        },
+      );
+      if (outcome === 'done') {
+        done += 1;
+      } else {
+        failed += 1;
+      }
+    }
+    return { claimed, done, failed };
+  }
+
+  private async tick(): Promise<void> {
+    if (this.ticking) {
+      return;
+    }
+    this.ticking = true;
+    try {
+      const result = await this.runOnce();
+      if (result.claimed > 0) {
+        this.logger.log(
+          `Export cycle: claimed ${result.claimed}, done ${result.done}, failed ${result.failed}.`,
+        );
+      }
+    } catch (error) {
+      this.logger.error('Export cycle failed.', error instanceof Error ? error.stack : String(error));
+    } finally {
+      this.ticking = false;
+    }
+  }
+}

package/template/src/modules/reports/application/services/reports-exports.service.ts

@@ -0,0 +1,74 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import type { Readable } from 'node:stream';
+import { ReportExportService } from '@ftisindia/report-builder';
+import type { ExportOutcome, QuerySpec } from '@ftisindia/report-builder';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { ExportRequestDto } from '../../dto/export-request.dto';
+import { RequestReportsContext } from '../../infrastructure/request-reports-context';
+import { LocalDiskReportExportStorage } from '../../infrastructure/storage/local-disk-export-storage.adapter';
+import { withReportsErrorMapping } from './reports-error.mapper';
+
+const FORMAT_MIME: Record<string, string> = {
+  csv: 'text/csv',
+  xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
+
+/**
+ * Thin HTTP-facing wrapper over the engine's ReportExportService. The sync-vs-
+ * async split by ACTUAL size, snapshot consistency, exportable:false stripping,
+ * and the PII-egress audit all live in the engine (design §9). The controller
+ * turns the ExportOutcome union into a StreamableFile or a 202 job response.
+ *
+ * Async export files land in the reports-OWNED export storage (no dependency
+ * on the forms file machinery); `download` streams a finished job's file back.
+ */
+@Injectable()
+export class ReportsExportsService {
+  constructor(
+    private readonly engine: ReportExportService,
+    private readonly reportsContext: RequestReportsContext,
+    private readonly requestContext: RequestContextService,
+    private readonly storage: LocalDiskReportExportStorage,
+  ) {}
+
+  async requestExport(orgId: string, key: string, dto: ExportRequestDto): Promise<ExportOutcome> {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() =>
+      this.engine.requestExport(
+        orgId,
+        key,
+        {
+          format: dto.format,
+          spec: dto.spec as unknown as QuerySpec | undefined,
+          columns: dto.columns,
+        },
+        this.reportsContext,
+      ),
+    );
+  }
+
+  async getJob(orgId: string, jobId: string) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() => this.engine.getJob(orgId, jobId, this.reportsContext));
+  }
+
+  /** Stream a finished async-export file (the job's fileId is its storage key). */
+  async download(
+    orgId: string,
+    jobId: string,
+  ): Promise<{ stream: Readable; fileName: string; mimeType: string }> {
+    this.requestContext.assertOrgScope(orgId);
+    const job = await withReportsErrorMapping(() =>
+      this.engine.getJob(orgId, jobId, this.reportsContext),
+    );
+    if (job.status !== 'DONE' || job.fileId === null) {
+      throw new NotFoundException('The export is not ready for download.');
+    }
+    const format = job.spec.format;
+    return {
+      stream: this.storage.read(job.fileId),
+      fileName: `${job.reportKey}-v${job.reportVersion}.${format}`,
+      mimeType: FORMAT_MIME[format] ?? 'application/octet-stream',
+    };
+  }
+}

package/template/src/modules/reports/application/services/reports-queries.service.ts

@@ -0,0 +1,35 @@
+import { Injectable } from '@nestjs/common';
+import { ReportQueryService } from '@ftisindia/report-builder';
+import type { QuerySpec } from '@ftisindia/report-builder';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { QuerySpecDto } from '../../dto/query-spec.dto';
+import { RequestReportsContext } from '../../infrastructure/request-reports-context';
+import { withReportsErrorMapping } from './reports-error.mapper';
+
+/**
+ * Thin HTTP-facing wrapper over the engine's ReportQueryService — THE grid
+ * endpoint plus the self-describing meta descriptor (design §4). The DTO
+ * validated the envelope; the engine's compiler validates the semantics.
+ */
+@Injectable()
+export class ReportsQueriesService {
+  constructor(
+    private readonly engine: ReportQueryService,
+    private readonly reportsContext: RequestReportsContext,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async query(orgId: string, key: string, spec: QuerySpecDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() =>
+      this.engine.query(orgId, key, spec as unknown as QuerySpec, this.reportsContext),
+    );
+  }
+
+  async meta(orgId: string, key: string, version: number | null) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() =>
+      this.engine.meta(orgId, key, version, this.reportsContext),
+    );
+  }
+}

package/template/src/modules/reports/application/services/reports-settings-reader.service.ts

@@ -0,0 +1,49 @@
+import { Injectable } from '@nestjs/common';
+import { DEFAULT_REPORTS_POLICY } from '@ftisindia/report-builder';
+import type { ReportsPolicy } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { settingDefinitions } from '../../../settings/types/setting-definitions';
+
+const REPORTS_SETTING_KEYS = [
+  'reports.statementTimeoutMs',
+  'reports.exportMaxSnapshotSeconds',
+  'reports.maxRowsSync',
+  'reports.countCap',
+  'reports.liveTierMaxRows',
+  'reports.resultCacheTtlMs',
+  'reports.tagVocabulary',
+] as const;
+
+/**
+ * Reads the org's reports policy from typed settings, falling back to the
+ * setting definitions' defaults for unset keys (the SettingsService 404s on
+ * unset keys, which is wrong for policy reads). Keys without a setting (page
+ * sizes, batch sizes, token TTLs, ...) keep the engine's DEFAULT_REPORTS_POLICY
+ * values. The result feeds every engine call that takes a ReportsPolicy —
+ * statement budgets, count caps, tier gates, export bounds (design §5.2/§8/§9).
+ */
+@Injectable()
+export class ReportsSettingsReader {
+  constructor(private readonly prisma: PrismaService) {}
+
+  async policyFor(orgId: string): Promise<ReportsPolicy> {
+    const rows = await this.prisma.organisationSetting.findMany({
+      where: { orgId, key: { in: [...REPORTS_SETTING_KEYS] } },
+      select: { key: true, value: true },
+    });
+    const values = new Map(rows.map((row) => [row.key, row.value as unknown]));
+    const read = <T>(key: (typeof REPORTS_SETTING_KEYS)[number]): T =>
+      (values.has(key) ? values.get(key) : settingDefinitions[key].defaultValue) as T;
+
+    return {
+      ...DEFAULT_REPORTS_POLICY,
+      statementTimeoutMs: read<number>('reports.statementTimeoutMs'),
+      exportMaxSnapshotSeconds: read<number>('reports.exportMaxSnapshotSeconds'),
+      maxRowsSync: read<number>('reports.maxRowsSync'),
+      countCap: read<number>('reports.countCap'),
+      liveTierMaxRows: read<number>('reports.liveTierMaxRows'),
+      resultCacheTtlMs: read<number>('reports.resultCacheTtlMs'),
+      tagVocabulary: read<string[]>('reports.tagVocabulary'),
+    };
+  }
+}

package/template/src/modules/reports/application/services/reports-views.service.ts

@@ -0,0 +1,79 @@
+import { Injectable } from '@nestjs/common';
+import { ReportViewService } from '@ftisindia/report-builder';
+import type { QuerySpec } from '@ftisindia/report-builder';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { CreateSavedViewDto } from '../../dto/create-saved-view.dto';
+import { ListViewsQueryDto } from '../../dto/list-views-query.dto';
+import { UpdateSavedViewDto } from '../../dto/update-saved-view.dto';
+import { RequestReportsContext } from '../../infrastructure/request-reports-context';
+import { withReportsErrorMapping } from './reports-error.mapper';
+
+/**
+ * Thin HTTP-facing wrapper over the engine's ReportViewService. Personal vs
+ * shared semantics (ownerId null ⇒ shared, gated by reports.update) and the
+ * per-view compatibility verdicts live in the engine (design §4, finding #9).
+ */
+@Injectable()
+export class ReportsViewsService {
+  constructor(
+    private readonly engine: ReportViewService,
+    private readonly reportsContext: RequestReportsContext,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async list(orgId: string, key: string, query: ListViewsQueryDto) {
+    this.requestContext.assertOrgScope(orgId);
+    const items = await withReportsErrorMapping(() =>
+      this.engine.list(orgId, key, query.version ?? null, this.reportsContext),
+    );
+    return { items };
+  }
+
+  async createPersonal(orgId: string, key: string, dto: CreateSavedViewDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() =>
+      this.engine.createPersonal(
+        orgId,
+        key,
+        { name: dto.name, spec: dto.spec as unknown as QuerySpec },
+        this.reportsContext,
+      ),
+    );
+  }
+
+  async createShared(orgId: string, key: string, dto: CreateSavedViewDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() =>
+      this.engine.createShared(
+        orgId,
+        key,
+        { name: dto.name, spec: dto.spec as unknown as QuerySpec },
+        this.reportsContext,
+      ),
+    );
+  }
+
+  async update(orgId: string, key: string, viewId: string, dto: UpdateSavedViewDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withReportsErrorMapping(() =>
+      this.engine.update(
+        orgId,
+        key,
+        viewId,
+        {
+          ...(dto.name === undefined ? {} : { name: dto.name }),
+          ...(dto.spec === undefined ? {} : { spec: dto.spec as unknown as QuerySpec }),
+        },
+        this.reportsContext,
+      ),
+    );
+  }
+
+  async delete(orgId: string, key: string, viewId: string) {
+    this.requestContext.assertOrgScope(orgId);
+    await withReportsErrorMapping(() =>
+      this.engine.delete(orgId, key, viewId, this.reportsContext),
+    );
+    return { deleted: true };
+  }
+}

package/template/src/modules/reports/dto/action-result-response.dto.ts

@@ -0,0 +1,21 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class ActionResultResponseDto {
+  @ApiProperty({ enum: ['DONE'], example: 'DONE' })
+  status!: 'DONE';
+
+  @ApiProperty({ example: 240 })
+  affectedRows!: number;
+
+  @ApiProperty({
+    nullable: true,
+    description: 'Whatever the delegated handler returned (e.g. { updated: 12 }).',
+  })
+  result!: unknown;
+
+  @ApiProperty({
+    example: false,
+    description: 'True when this call replayed a previously recorded idempotent run (§6.3).',
+  })
+  replayed!: boolean;
+}