@ftisindia/create-app 0.1.5 → 0.2.0

package/template/src/modules/forms/presentation/forms-submissions.controller.ts

@@ -0,0 +1,154 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Header,
+  HttpCode,
+  Param,
+  ParseUUIDPipe,
+  Post,
+  Query,
+  Res,
+  UseGuards,
+} from '@nestjs/common';
+import type { Response } from 'express';
+import {
+  ApiBearerAuth,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+  ApiUnprocessableEntityResponse,
+} from '@nestjs/swagger';
+import { Throttle } from '@nestjs/throttler';
+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 { CurrentUser } from '../../auth/presentation/current-user.decorator';
+import { AuthenticatedUser } from '../../auth/types/authenticated-user';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { FormsExportService } from '../application/services/forms-export.service';
+import { FormsSubmissionsService } from '../application/services/forms-submissions.service';
+import { ExportSubmissionsQueryDto } from '../dto/export-submissions-query.dto';
+import { ListSubmissionsQueryDto } from '../dto/list-submissions-query.dto';
+import {
+  SubmissionListResponseDto,
+  SubmissionResponseDto,
+  SubmitResultResponseDto,
+  ValidationResultResponseDto,
+} from '../dto/submission-response.dto';
+import { SubmitFormDto } from '../dto/submit-form.dto';
+import { ValidateSubmissionDto } from '../dto/validate-submission.dto';
+
+@ApiTags('Forms')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiParam({ name: 'formKey', description: 'Form definition key.' })
+@ApiProtectedErrorResponses(404, 409)
+@ApiUnprocessableEntityResponse({
+  description: 'The submission data failed engine validation.',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/forms/:formKey/submissions')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class FormsSubmissionsController {
+  constructor(
+    private readonly formsSubmissionsService: FormsSubmissionsService,
+    private readonly formsExportService: FormsExportService,
+  ) {}
+
+  @Post()
+  @HttpCode(200)
+  @Throttle({ default: { limit: 30, ttl: 60_000 } })
+  @RequirePermissions('formSubmissions.create')
+  @ApiOperation({ summary: 'Submit form data or save a draft submission.' })
+  @ApiOkResponse({
+    description: 'Pipeline result.',
+    type: SubmitResultResponseDto,
+  })
+  submit(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Body() dto: SubmitFormDto,
+  ) {
+    return this.formsSubmissionsService.submit(orgId, formKey, dto, user);
+  }
+
+  @Post('validate')
+  @HttpCode(200)
+  @RequirePermissions('formSubmissions.create')
+  @ApiOperation({ summary: 'Validate submission data without side effects.' })
+  @ApiOkResponse({
+    description: 'Validation result.',
+    type: ValidationResultResponseDto,
+  })
+  validate(
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Body() dto: ValidateSubmissionDto,
+  ) {
+    return this.formsSubmissionsService.validate(orgId, formKey, dto);
+  }
+
+  @Get()
+  @RequirePermissions('formSubmissions.read')
+  @ApiOperation({ summary: 'List submissions for a form.' })
+  @ApiOkResponse({
+    description: 'Form submissions.',
+    type: SubmissionListResponseDto,
+  })
+  list(
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Query() query: ListSubmissionsQueryDto,
+  ) {
+    return this.formsSubmissionsService.list(orgId, formKey, query);
+  }
+
+  // Declared before GET :submissionId so the literal segment wins.
+  @Get('export')
+  @RequirePermissions('formSubmissions.export')
+  @Header('Cache-Control', 'no-store')
+  @ApiOperation({
+    summary:
+      'Export submissions (PII egress — separately permissioned and always audited). Defaults to reportable fields.',
+  })
+  @ApiOkResponse({ description: 'Export payload (JSON object or CSV body).' })
+  async export(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Query() query: ExportSubmissionsQueryDto,
+    @Res({ passthrough: true }) res: Response,
+  ) {
+    const result = await this.formsExportService.export(orgId, formKey, query, user);
+    if (result.format === 'csv') {
+      res.setHeader('Content-Type', 'text/csv; charset=utf-8');
+      res.setHeader(
+        'Content-Disposition',
+        `attachment; filename="${formKey}-submissions.csv"`,
+      );
+      return result.csv;
+    }
+    return { columns: result.columns, rows: result.rows };
+  }
+
+  @Get(':submissionId')
+  @RequirePermissions('formSubmissions.read')
+  @ApiParam({
+    name: 'submissionId',
+    description: 'Submission ID.',
+    format: 'uuid',
+  })
+  @ApiOperation({ summary: 'Return a single submission.' })
+  @ApiOkResponse({
+    description: 'Submission.',
+    type: SubmissionResponseDto,
+  })
+  get(@Param('orgId') orgId: string, @Param('submissionId', ParseUUIDPipe) submissionId: string) {
+    return this.formsSubmissionsService.get(orgId, submissionId);
+  }
+}

package/template/src/modules/forms/presentation/forms-upload.interceptor.ts

@@ -0,0 +1,33 @@
+import {
+  CallHandler,
+  ExecutionContext,
+  Injectable,
+  NestInterceptor,
+} from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { FileInterceptor } from '@nestjs/platform-express';
+import { memoryStorage } from 'multer';
+import type { Observable } from 'rxjs';
+
+@Injectable()
+export class FormsUploadInterceptor implements NestInterceptor {
+  private readonly delegate: NestInterceptor;
+
+  constructor(config: ConfigService) {
+    const maxUploadMb = config.get<number>('forms.maxUploadMb') ?? 25;
+    const Interceptor = FileInterceptor('file', {
+      storage: memoryStorage(),
+      limits: { fileSize: maxUploadMb * 1024 * 1024 },
+    });
+    this.delegate = new Interceptor();
+  }
+
+  intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Observable<unknown> | Promise<Observable<unknown>> {
+    return this.delegate.intercept(context, next) as
+      | Observable<unknown>
+      | Promise<Observable<unknown>>;
+  }
+}

package/template/src/modules/forms/presentation/public-forms.controller.ts

@@ -0,0 +1,51 @@
+import { Body, Controller, Get, HttpCode, Param, Post, UseGuards } from '@nestjs/common';
+import { ApiOkResponse, ApiOperation, ApiParam, ApiTags } from '@nestjs/swagger';
+import { Throttle } from '@nestjs/throttler';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { Public } from '../../access-control/presentation/public.decorator';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { FormsPublicService } from '../application/services/forms-public.service';
+import { FormRenderResponseDto } from '../dto/form-render-response.dto';
+import { PublicSubmitFormDto } from '../dto/public-submit-form.dto';
+import { SubmitResultResponseDto } from '../dto/submission-response.dto';
+
+/**
+ * Anonymous endpoints for definitions whose settings.access === 'public'
+ * (flipping that setting is gated by forms.managePublicAccess and audited).
+ * Like the auth routes, these carry no JwtAuthGuard/PermissionGuard and are
+ * NOT in the route-permission registry; they are throttled tighter than the
+ * app default, and the engine enforces the remaining Tier-1 abuse controls
+ * (per-IP/day caps, captcha, ip/ua stamping).
+ */
+@ApiTags('Forms (public)')
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiParam({ name: 'formKey', description: 'Form definition key.' })
+@ApiProtectedErrorResponses(404, 429)
+@Controller('public/organisations/:orgId/forms/:formKey')
+@UseGuards(OrgScopeGuard)
+export class PublicFormsController {
+  constructor(private readonly publicService: FormsPublicService) {}
+
+  @Get('render')
+  @Public()
+  @Throttle({ default: { limit: 30, ttl: 60_000 } })
+  @ApiOperation({ summary: 'Render a public form (definition + resolved options).' })
+  @ApiOkResponse({ description: 'Renderable definition.', type: FormRenderResponseDto })
+  render(@Param('orgId') orgId: string, @Param('formKey') formKey: string) {
+    return this.publicService.render(orgId, formKey);
+  }
+
+  @Post('submissions')
+  @Public()
+  @HttpCode(200)
+  @Throttle({ default: { limit: 10, ttl: 60_000 } })
+  @ApiOperation({ summary: 'Submit a public form anonymously.' })
+  @ApiOkResponse({ description: 'Submission result.', type: SubmitResultResponseDto })
+  submit(
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Body() dto: PublicSubmitFormDto,
+  ) {
+    return this.publicService.submit(orgId, formKey, dto);
+  }
+}

package/template/src/modules/invitations/dto/invitation-response.dto.ts

@@ -48,6 +48,7 @@ export class InvitationResponseDto {
   invitedByUserId!: string;
 
   @ApiPropertyOptional({
+    type: String,
     example: '7efd9a26-fbec-4511-ae37-7fb1c35e5215',
     format: 'uuid',
     nullable: true,
@@ -67,6 +68,7 @@ export class InvitationResponseDto {
   createdAt!: string;
 
   @ApiPropertyOptional({
+    type: String,
     example: '2026-06-01T10:35:00.000Z',
     format: 'date-time',
     nullable: true,
@@ -74,6 +76,7 @@ export class InvitationResponseDto {
   acceptedAt?: string | null;
 
   @ApiPropertyOptional({
+    type: String,
     example: '2026-06-01T10:40:00.000Z',
     format: 'date-time',
     nullable: true,
@@ -97,6 +100,7 @@ export class InvitationListResponseDto {
   items!: InvitationResponseDto[];
 
   @ApiPropertyOptional({
+    type: String,
     example: '17a21ad7-bd1b-42d8-b809-0a3892bb60c3',
     format: 'uuid',
     nullable: true,

package/template/src/modules/organisations/dto/organisation-response.dto.ts

@@ -105,6 +105,7 @@ export class MyOrganisationListResponseDto {
   items!: MyOrganisationResponseDto[];
 
   @ApiProperty({
+    type: String,
     example: '2c67399d-670c-4025-a5fd-1ea9a211891e',
     format: 'uuid',
     nullable: true,

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