@ftisindia/create-app 0.1.4 → 0.1.6

package/template/src/modules/reports/infrastructure/stores/prisma-saved-view.store.ts

@@ -0,0 +1,144 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma, ReportSavedView as ReportSavedViewRow } from '@prisma/client';
+import {
+  ReportConflictError,
+  ReportNotFoundError,
+  type EngineTx,
+  type NewSavedViewRecord,
+  type QuerySpec,
+  type SavedViewRecord,
+  type SavedViewStore,
+} from '@ftisindia/report-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+
+@Injectable()
+export class PrismaSavedViewStore implements SavedViewStore {
+  constructor(private readonly prisma: PrismaService) {}
+
+  private client(tx?: EngineTx) {
+    return tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+  }
+
+  async create(record: NewSavedViewRecord, tx?: EngineTx): Promise<SavedViewRecord> {
+    try {
+      const row = await this.client(tx).reportSavedView.create({
+        data: {
+          orgId: record.orgId,
+          reportKey: record.reportKey,
+          reportVersion: record.reportVersion,
+          name: record.name,
+          spec: record.spec as unknown as Prisma.InputJsonValue,
+          ownerId: record.ownerId,
+        },
+      });
+
+      return this.toRecord(row);
+    } catch (error) {
+      if (this.isDuplicateViewName(error)) {
+        throw new ReportConflictError(
+          `A view named "${record.name}" already exists for this report.`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  async update(
+    orgId: string,
+    id: string,
+    patch: { name?: string; spec?: QuerySpec; reportVersion?: number },
+    tx?: EngineTx,
+  ): Promise<SavedViewRecord> {
+    const client = this.client(tx);
+
+    const existing = await client.reportSavedView.findFirst({
+      where: { id, orgId },
+      select: { id: true },
+    });
+
+    if (!existing) {
+      throw new ReportNotFoundError(`Saved view ${id} was not found in this organisation.`);
+    }
+
+    try {
+      const row = await client.reportSavedView.update({
+        where: { id: existing.id },
+        data: {
+          ...(patch.name !== undefined ? { name: patch.name } : {}),
+          ...(patch.spec !== undefined
+            ? { spec: patch.spec as unknown as Prisma.InputJsonValue }
+            : {}),
+          ...(patch.reportVersion !== undefined ? { reportVersion: patch.reportVersion } : {}),
+        },
+      });
+
+      return this.toRecord(row);
+    } catch (error) {
+      if (this.isDuplicateViewName(error)) {
+        throw new ReportConflictError(
+          patch.name === undefined
+            ? 'A view with this name already exists for this report.'
+            : `A view named "${patch.name}" already exists for this report.`,
+        );
+      }
+      throw error;
+    }
+  }
+
+  async delete(orgId: string, id: string, tx?: EngineTx): Promise<void> {
+    await this.client(tx).reportSavedView.deleteMany({
+      where: { id, orgId },
+    });
+  }
+
+  async findById(orgId: string, id: string): Promise<SavedViewRecord | null> {
+    const row = await this.client().reportSavedView.findFirst({
+      where: { id, orgId },
+    });
+
+    return row ? this.toRecord(row) : null;
+  }
+
+  async listByReport(
+    orgId: string,
+    reportKey: string,
+    userId: string,
+  ): Promise<SavedViewRecord[]> {
+    const rows = await this.client().reportSavedView.findMany({
+      // The caller's PERSONAL views plus SHARED views (ownerId null) — never
+      // another user's personal views (report design §4/§12).
+      where: { orgId, reportKey, OR: [{ ownerId: userId }, { ownerId: null }] },
+      orderBy: [{ name: 'asc' }, { createdAt: 'asc' }],
+    });
+
+    return rows.map((row) => this.toRecord(row));
+  }
+
+  /**
+   * View-name uniqueness lives in PARTIAL UNIQUE INDEXES shipped as raw SQL
+   * (report design §12, finding #5 — Postgres treats NULL ownerIds as
+   * distinct, so a Prisma @@unique cannot express it). Prisma maps the
+   * underlying 23505 to P2002 when it can; a raw partial-unique violation may
+   * also surface as an unknown request error, so match the index-name prefix
+   * ("report_view_shared_uq" / "report_view_personal_uq") as the fallback.
+   */
+  private isDuplicateViewName(error: unknown): boolean {
+    if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002') {
+      return true;
+    }
+    return error instanceof Error && error.message.includes('report_view_');
+  }
+
+  private toRecord(row: ReportSavedViewRow): SavedViewRecord {
+    return {
+      id: row.id,
+      orgId: row.orgId,
+      reportKey: row.reportKey,
+      reportVersion: row.reportVersion,
+      name: row.name,
+      spec: row.spec as unknown as QuerySpec,
+      ownerId: row.ownerId,
+      createdAt: row.createdAt,
+    };
+  }
+}

package/template/src/modules/reports/presentation/reports-actions.controller.ts

@@ -0,0 +1,83 @@
+import { Body, Controller, HttpCode, Param, Post, UseGuards } from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+  ApiUnprocessableEntityResponse,
+} from '@nestjs/swagger';
+import { ErrorResponseDto } from '../../../common/dto/error-response.dto';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { PermissionGuard } from '../../access-control/application/services/permission.guard';
+import { RequirePermissions } from '../../access-control/presentation/permissions.decorator';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { ReportsActionsService } from '../application/services/reports-actions.service';
+import { ActionResultResponseDto } from '../dto/action-result-response.dto';
+import { ExecuteActionDto } from '../dto/execute-action.dto';
+import { PrepareActionDto } from '../dto/prepare-action.dto';
+import { PrepareActionResponseDto } from '../dto/prepare-action-response.dto';
+
+/**
+ * Row actions (design §6) — verbs that DELEGATE, never a second write path.
+ * The route-level key is reports.read (the grid entry point); each action's
+ * own permission keys (action.requiredPermissions, e.g.
+ * 'formSubmissions.update') are enforced INSIDE the engine at execute-time —
+ * the second of §6.1's two layers (attach-time ran at definition save).
+ */
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiParam({ name: 'key', description: 'Report definition key.' })
+@ApiParam({ name: 'name', description: 'Registered row-action name.' })
+@ApiProtectedErrorResponses(404, 409, 410)
+@ApiUnprocessableEntityResponse({
+  description: 'The action input failed validation.',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/reports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsActionsController {
+  constructor(private readonly reportsActionsService: ReportsActionsService) {}
+
+  @Post(':key/actions/:name/prepare')
+  @HttpCode(200)
+  @RequirePermissions('reports.read')
+  @ApiOperation({
+    summary:
+      'Prepare a byFilter bulk action: resolve the selection NOW and sign what was seen (§6.3 step 1).',
+  })
+  @ApiOkResponse({
+    description: 'Expected count plus the signed, short-TTL action token.',
+    type: PrepareActionResponseDto,
+  })
+  prepare(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Param('name') name: string,
+    @Body() dto: PrepareActionDto,
+  ) {
+    return this.reportsActionsService.prepare(orgId, key, name, dto);
+  }
+
+  @Post(':key/actions/:name')
+  @HttpCode(200)
+  @RequirePermissions('reports.read')
+  @ApiOperation({
+    summary:
+      'Execute a row/bulk action: byIds directly, byFilter via the prepared token with drift detection and the idempotency ledger (§6.3).',
+  })
+  @ApiOkResponse({
+    description: 'Execution outcome.',
+    type: ActionResultResponseDto,
+  })
+  execute(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Param('name') name: string,
+    @Body() dto: ExecuteActionDto,
+  ) {
+    return this.reportsActionsService.execute(orgId, key, name, dto);
+  }
+}

package/template/src/modules/reports/presentation/reports-definitions.controller.ts

@@ -0,0 +1,156 @@
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Param,
+  Patch,
+  Post,
+  Query,
+  UseGuards,
+} from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiCreatedResponse,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+  ApiUnprocessableEntityResponse,
+} from '@nestjs/swagger';
+import { ErrorResponseDto } from '../../../common/dto/error-response.dto';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { PermissionGuard } from '../../access-control/application/services/permission.guard';
+import { RequirePermissions } from '../../access-control/presentation/permissions.decorator';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { ReportsDefinitionsService } from '../application/services/reports-definitions.service';
+import { ReportsQueriesService } from '../application/services/reports-queries.service';
+import { CreateReportDefinitionDto } from '../dto/create-report-definition.dto';
+import { ListReportsQueryDto } from '../dto/list-reports-query.dto';
+import {
+  ReportArchivedResponseDto,
+  ReportDefinitionListResponseDto,
+  ReportDefinitionResponseDto,
+} from '../dto/report-definition-response.dto';
+import { ReportMetaQueryDto } from '../dto/report-meta-query.dto';
+import { ReportMetaResponseDto } from '../dto/report-meta-response.dto';
+import { UpdateReportDefinitionDto } from '../dto/update-report-definition.dto';
+
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404, 409)
+@ApiUnprocessableEntityResponse({
+  description: 'The report definition failed engine validation or linting (§5.2/§8).',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/reports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsDefinitionsController {
+  constructor(
+    private readonly reportsDefinitionsService: ReportsDefinitionsService,
+    private readonly reportsQueriesService: ReportsQueriesService,
+  ) {}
+
+  @Get()
+  @RequirePermissions('reports.read')
+  @ApiOperation({ summary: 'List report definitions.' })
+  @ApiOkResponse({
+    description: 'Report definitions.',
+    type: ReportDefinitionListResponseDto,
+  })
+  list(@Param('orgId') orgId: string, @Query() query: ListReportsQueryDto) {
+    return this.reportsDefinitionsService.list(orgId, query);
+  }
+
+  @Post()
+  @RequirePermissions('reports.create')
+  @ApiOperation({ summary: 'Create a new draft report definition version.' })
+  @ApiCreatedResponse({
+    description: 'Created draft definition.',
+    type: ReportDefinitionResponseDto,
+  })
+  create(@Param('orgId') orgId: string, @Body() dto: CreateReportDefinitionDto) {
+    return this.reportsDefinitionsService.create(orgId, dto);
+  }
+
+  @Get(':key')
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({ summary: 'Return the latest version of a report definition.' })
+  @ApiOkResponse({
+    description: 'Latest definition version.',
+    type: ReportDefinitionResponseDto,
+  })
+  getLatest(@Param('orgId') orgId: string, @Param('key') key: string) {
+    return this.reportsDefinitionsService.getLatest(orgId, key);
+  }
+
+  @Patch(':key')
+  @RequirePermissions('reports.update')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'Edit the draft. Editing a published version opens a new draft version (published rows are immutable, §2).',
+  })
+  @ApiOkResponse({
+    description: 'Updated draft definition.',
+    type: ReportDefinitionResponseDto,
+  })
+  update(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Body() dto: UpdateReportDefinitionDto,
+  ) {
+    return this.reportsDefinitionsService.update(orgId, key, dto);
+  }
+
+  @Post(':key/publish')
+  @HttpCode(200)
+  @RequirePermissions('reports.publish')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'Publish the latest draft: the §5.2 layered lint runs here, failing constructively with the suggested migration SQL (§8).',
+  })
+  @ApiOkResponse({
+    description: 'Published definition.',
+    type: ReportDefinitionResponseDto,
+  })
+  publish(@Param('orgId') orgId: string, @Param('key') key: string) {
+    return this.reportsDefinitionsService.publish(orgId, key);
+  }
+
+  @Post(':key/archive')
+  @HttpCode(200)
+  @RequirePermissions('reports.archive')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({ summary: 'Archive every version of a report definition.' })
+  @ApiOkResponse({
+    description: 'Archive confirmation.',
+    type: ReportArchivedResponseDto,
+  })
+  archive(@Param('orgId') orgId: string, @Param('key') key: string) {
+    return this.reportsDefinitionsService.archive(orgId, key);
+  }
+
+  @Get(':key/meta')
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'Return the self-describing grid descriptor: columns, typed operators, actions, export config (§4).',
+  })
+  @ApiOkResponse({
+    description: 'Report metadata descriptor.',
+    type: ReportMetaResponseDto,
+  })
+  meta(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Query() query: ReportMetaQueryDto,
+  ) {
+    return this.reportsQueriesService.meta(orgId, key, query.version ?? null);
+  }
+}

package/template/src/modules/reports/presentation/reports-export-jobs.controller.ts

@@ -0,0 +1,61 @@
+import { Controller, Get, Param, ParseUUIDPipe, StreamableFile, UseGuards } from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiProduces,
+  ApiTags,
+} from '@nestjs/swagger';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { PermissionGuard } from '../../access-control/application/services/permission.guard';
+import { RequirePermissions } from '../../access-control/presentation/permissions.decorator';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { ReportsExportsService } from '../application/services/reports-exports.service';
+import { ExportJobResponseDto } from '../dto/export-job-response.dto';
+
+/**
+ * MUST be registered BEFORE ReportsDefinitionsController in the module's
+ * controllers array: both controllers share the 'organisations/:orgId/reports'
+ * base path, and the literal 'exports' segment has to win over the ':key'
+ * parameter route ('exports' is a reserved report key for the same reason).
+ */
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404)
+@Controller('organisations/:orgId/reports/exports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsExportJobsController {
+  constructor(private readonly reportsExportsService: ReportsExportsService) {}
+
+  @Get(':jobId')
+  @RequirePermissions('reports.export')
+  @ApiParam({ name: 'jobId', description: 'Export job ID.', format: 'uuid' })
+  @ApiOperation({ summary: 'Return the status of an async export job (§9/§10).' })
+  @ApiOkResponse({
+    description: 'Export job status.',
+    type: ExportJobResponseDto,
+  })
+  getJob(@Param('orgId') orgId: string, @Param('jobId', ParseUUIDPipe) jobId: string) {
+    return this.reportsExportsService.getJob(orgId, jobId);
+  }
+
+  @Get(':jobId/download')
+  @RequirePermissions('reports.export')
+  @ApiParam({ name: 'jobId', description: 'Export job ID.', format: 'uuid' })
+  @ApiOperation({ summary: 'Download a finished async export file (§9).' })
+  @ApiProduces('text/csv', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet')
+  @ApiOkResponse({ description: 'The export file stream.' })
+  async download(
+    @Param('orgId') orgId: string,
+    @Param('jobId', ParseUUIDPipe) jobId: string,
+  ): Promise<StreamableFile> {
+    const file = await this.reportsExportsService.download(orgId, jobId);
+    return new StreamableFile(file.stream, {
+      type: file.mimeType,
+      disposition: `attachment; filename="${file.fileName}"`,
+    });
+  }
+}

package/template/src/modules/reports/presentation/reports-export.controller.ts

@@ -0,0 +1,76 @@
+import {
+  Body,
+  Controller,
+  Header,
+  HttpCode,
+  Param,
+  Post,
+  Res,
+  StreamableFile,
+  UseGuards,
+} from '@nestjs/common';
+import { Readable } from 'node:stream';
+import type { Response } from 'express';
+import {
+  ApiAcceptedResponse,
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+  ApiUnprocessableEntityResponse,
+} from '@nestjs/swagger';
+import { ErrorResponseDto } from '../../../common/dto/error-response.dto';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { PermissionGuard } from '../../access-control/application/services/permission.guard';
+import { RequirePermissions } from '../../access-control/presentation/permissions.decorator';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { ReportsExportsService } from '../application/services/reports-exports.service';
+import { ExportJobResponseDto } from '../dto/export-job-response.dto';
+import { ExportRequestDto } from '../dto/export-request.dto';
+
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404)
+@ApiUnprocessableEntityResponse({
+  description: 'The export was rejected (snapshot bound exceeded, no exportable columns, §9).',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/reports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsExportController {
+  constructor(private readonly reportsExportsService: ReportsExportsService) {}
+
+  @Post(':key/export')
+  @HttpCode(200)
+  @Header('Cache-Control', 'no-store')
+  @RequirePermissions('reports.export')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'Export report rows (PII egress — separately permissioned, always audited): sync stream up to the cap, 202 job above it (§9).',
+  })
+  @ApiOkResponse({ description: 'The export file stream (CSV or XLSX).' })
+  @ApiAcceptedResponse({
+    description: 'The selection exceeds the sync cap; an async export job was queued.',
+    type: ExportJobResponseDto,
+  })
+  async export(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Body() dto: ExportRequestDto,
+    @Res({ passthrough: true }) res: Response,
+  ) {
+    const outcome = await this.reportsExportsService.requestExport(orgId, key, dto);
+    if (outcome.kind === 'stream') {
+      return new StreamableFile(Readable.from(outcome.stream), {
+        type: outcome.mimeType,
+        disposition: `attachment; filename="${outcome.fileName}"`,
+      });
+    }
+    res.status(202);
+    return outcome.job;
+  }
+}

package/template/src/modules/reports/presentation/reports-query.controller.ts

@@ -0,0 +1,52 @@
+import { Body, Controller, HttpCode, Param, Post, UseGuards } from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiRequestTimeoutResponse,
+  ApiTags,
+} from '@nestjs/swagger';
+import { ErrorResponseDto } from '../../../common/dto/error-response.dto';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { PermissionGuard } from '../../access-control/application/services/permission.guard';
+import { RequirePermissions } from '../../access-control/presentation/permissions.decorator';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { ReportsQueriesService } from '../application/services/reports-queries.service';
+import { QueryResponseDto } from '../dto/query-response.dto';
+import { QuerySpecDto } from '../dto/query-spec.dto';
+
+@ApiTags('Reports')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404)
+@ApiRequestTimeoutResponse({
+  description: 'The report query exceeded its statement budget (§5.2).',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/reports')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class ReportsQueryController {
+  constructor(private readonly reportsQueriesService: ReportsQueriesService) {}
+
+  @Post(':key/query')
+  @HttpCode(200)
+  @RequirePermissions('reports.read')
+  @ApiParam({ name: 'key', description: 'Report definition key.' })
+  @ApiOperation({
+    summary:
+      'THE grid endpoint (§4): one declarative QuerySpec for filters, search, sort, keyset paging, counts, and projection.',
+  })
+  @ApiOkResponse({
+    description: 'Query result page.',
+    type: QueryResponseDto,
+  })
+  query(
+    @Param('orgId') orgId: string,
+    @Param('key') key: string,
+    @Body() spec: QuerySpecDto,
+  ) {
+    return this.reportsQueriesService.query(orgId, key, spec);
+  }
+}