@ftisindia/create-app 0.1.5 → 0.1.6

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

@@ -0,0 +1,191 @@
+import {
+  Body,
+  Controller,
+  Get,
+  HttpCode,
+  Param,
+  ParseIntPipe,
+  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 { FormsDefinitionsService } from '../application/services/forms-definitions.service';
+import { CreateFormDefinitionDto } from '../dto/create-form-definition.dto';
+import {
+  FormDefinitionListResponseDto,
+  FormDefinitionResponseDto,
+} from '../dto/form-definition-response.dto';
+import { FormRenderResponseDto } from '../dto/form-render-response.dto';
+import { ListFormDefinitionsQueryDto } from '../dto/list-form-definitions-query.dto';
+import { SetPublicAccessDto } from '../dto/set-public-access.dto';
+import { UpdateFormDefinitionDto } from '../dto/update-form-definition.dto';
+
+@ApiTags('Forms')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiProtectedErrorResponses(404, 409)
+@ApiUnprocessableEntityResponse({
+  description: 'The form definition failed engine validation or linting.',
+  type: ErrorResponseDto,
+})
+@Controller('organisations/:orgId/forms')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class FormsDefinitionsController {
+  constructor(private readonly formsDefinitionsService: FormsDefinitionsService) {}
+
+  @Get()
+  @RequirePermissions('forms.read')
+  @ApiOperation({ summary: 'List form definitions.' })
+  @ApiOkResponse({
+    description: 'Form definitions.',
+    type: FormDefinitionListResponseDto,
+  })
+  list(@Param('orgId') orgId: string, @Query() query: ListFormDefinitionsQueryDto) {
+    return this.formsDefinitionsService.list(orgId, query);
+  }
+
+  @Post()
+  @RequirePermissions('forms.create')
+  @ApiOperation({ summary: 'Create a new draft form definition version.' })
+  @ApiCreatedResponse({
+    description: 'Created draft definition.',
+    type: FormDefinitionResponseDto,
+  })
+  create(@Param('orgId') orgId: string, @Body() dto: CreateFormDefinitionDto) {
+    return this.formsDefinitionsService.create(orgId, dto);
+  }
+
+  @Get(':formKey')
+  @RequirePermissions('forms.read')
+  @ApiParam({ name: 'formKey', description: 'Form definition key.' })
+  @ApiOperation({ summary: 'Return the latest version of a form definition.' })
+  @ApiOkResponse({
+    description: 'Latest definition version.',
+    type: FormDefinitionResponseDto,
+  })
+  getLatest(@Param('orgId') orgId: string, @Param('formKey') formKey: string) {
+    return this.formsDefinitionsService.getLatest(orgId, formKey);
+  }
+
+  @Get(':formKey/render')
+  @RequirePermissions('formSubmissions.create')
+  @ApiParam({ name: 'formKey', description: 'Form definition key.' })
+  @ApiOperation({
+    summary: 'Return the published definition plus resolved data-source options.',
+  })
+  @ApiOkResponse({
+    description: 'Renderable definition.',
+    type: FormRenderResponseDto,
+  })
+  render(@Param('orgId') orgId: string, @Param('formKey') formKey: string) {
+    return this.formsDefinitionsService.render(orgId, formKey);
+  }
+
+  @Get(':formKey/versions/:version')
+  @RequirePermissions('forms.read')
+  @ApiParam({ name: 'formKey', description: 'Form definition key.' })
+  @ApiParam({ name: 'version', description: 'Definition version number.', type: Number })
+  @ApiOperation({ summary: 'Return a specific form definition version.' })
+  @ApiOkResponse({
+    description: 'Definition version.',
+    type: FormDefinitionResponseDto,
+  })
+  getVersion(
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Param('version', ParseIntPipe) version: number,
+  ) {
+    return this.formsDefinitionsService.getVersion(orgId, formKey, version);
+  }
+
+  @Patch(':formKey/versions/:version')
+  @RequirePermissions('forms.update')
+  @ApiParam({ name: 'formKey', description: 'Form definition key.' })
+  @ApiParam({ name: 'version', description: 'Definition version number.', type: Number })
+  @ApiOperation({ summary: 'Update a draft form definition version.' })
+  @ApiOkResponse({
+    description: 'Updated draft definition.',
+    type: FormDefinitionResponseDto,
+  })
+  update(
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Param('version', ParseIntPipe) version: number,
+    @Body() dto: UpdateFormDefinitionDto,
+  ) {
+    return this.formsDefinitionsService.update(orgId, formKey, version, dto);
+  }
+
+  @Post(':formKey/versions/:version/publish')
+  @HttpCode(200)
+  @RequirePermissions('forms.publish')
+  @ApiParam({ name: 'formKey', description: 'Form definition key.' })
+  @ApiParam({ name: 'version', description: 'Definition version number.', type: Number })
+  @ApiOperation({ summary: 'Publish a draft form definition version.' })
+  @ApiOkResponse({
+    description: 'Published definition.',
+    type: FormDefinitionResponseDto,
+  })
+  publish(
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Param('version', ParseIntPipe) version: number,
+  ) {
+    return this.formsDefinitionsService.publish(orgId, formKey, version);
+  }
+
+  @Post(':formKey/versions/:version/archive')
+  @HttpCode(200)
+  @RequirePermissions('forms.archive')
+  @ApiParam({ name: 'formKey', description: 'Form definition key.' })
+  @ApiParam({ name: 'version', description: 'Definition version number.', type: Number })
+  @ApiOperation({ summary: 'Archive a form definition version.' })
+  @ApiOkResponse({
+    description: 'Archived definition.',
+    type: FormDefinitionResponseDto,
+  })
+  archive(
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Param('version', ParseIntPipe) version: number,
+  ) {
+    return this.formsDefinitionsService.archive(orgId, formKey, version);
+  }
+
+  @Post(':formKey/versions/:version/public-access')
+  @HttpCode(200)
+  @RequirePermissions('forms.managePublicAccess')
+  @ApiParam({ name: 'formKey', description: 'Form definition key.' })
+  @ApiParam({ name: 'version', description: 'Definition version number.', type: Number })
+  @ApiOperation({
+    summary: 'Flip the public/private access setting on a form definition version.',
+  })
+  @ApiOkResponse({
+    description: 'Updated definition.',
+    type: FormDefinitionResponseDto,
+  })
+  setPublicAccess(
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Param('version', ParseIntPipe) version: number,
+    @Body() dto: SetPublicAccessDto,
+  ) {
+    return this.formsDefinitionsService.setPublicAccess(orgId, formKey, version, dto);
+  }
+}

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

@@ -0,0 +1,79 @@
+import {
+  Controller,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Post,
+  Query,
+  UploadedFile,
+  UseGuards,
+  UseInterceptors,
+} from '@nestjs/common';
+import {
+  ApiBearerAuth,
+  ApiBody,
+  ApiConsumes,
+  ApiOkResponse,
+  ApiOperation,
+  ApiParam,
+  ApiTags,
+} from '@nestjs/swagger';
+import { ApiProtectedErrorResponses } from '../../../common/swagger/api-error-responses';
+import { CurrentUser } from '../../auth/presentation/current-user.decorator';
+import { JwtAuthGuard } from '../../auth/infrastructure/passport/jwt-auth.guard';
+import { AuthenticatedUser } from '../../auth/types/authenticated-user';
+import { PermissionGuard } from '../../access-control/application/services/permission.guard';
+import { RequirePermissions } from '../../access-control/presentation/permissions.decorator';
+import { OrgScopeGuard } from '../../request-context/presentation/org-scope.guard';
+import { FileUploadResponseDto } from '../dto/file-upload-response.dto';
+import { UploadFileQueryDto } from '../dto/upload-file-query.dto';
+import { FormsFilesService } from '../application/services/forms-files.service';
+import { FormsUploadInterceptor } from './forms-upload.interceptor';
+
+@ApiTags('Forms')
+@ApiBearerAuth()
+@ApiParam({ name: 'orgId', description: 'Organisation ID.', format: 'uuid' })
+@ApiParam({ name: 'formKey', description: 'Form definition key.' })
+@ApiProtectedErrorResponses(404, 409)
+@Controller('organisations/:orgId/forms/:formKey/files')
+@UseGuards(JwtAuthGuard, OrgScopeGuard, PermissionGuard)
+export class FormsFilesController {
+  constructor(private readonly filesService: FormsFilesService) {}
+
+  @Post()
+  @RequirePermissions('formSubmissions.create')
+  @UseInterceptors(FormsUploadInterceptor)
+  @ApiConsumes('multipart/form-data')
+  @ApiBody({
+    schema: {
+      type: 'object',
+      properties: { file: { type: 'string', format: 'binary' } },
+      required: ['file'],
+    },
+  })
+  @ApiOperation({
+    summary:
+      'Upload a file for a form field (before submit). The submission then references the returned fileId.',
+  })
+  @ApiOkResponse({ description: 'Uploaded file reference.', type: FileUploadResponseDto })
+  upload(
+    @CurrentUser() user: AuthenticatedUser,
+    @Param('orgId') orgId: string,
+    @Param('formKey') formKey: string,
+    @Query() query: UploadFileQueryDto,
+    @UploadedFile() file: { originalname: string; size: number; buffer: Buffer } | undefined,
+  ) {
+    return this.filesService.upload(orgId, formKey, query, file, user);
+  }
+
+  @Get(':fileId')
+  @RequirePermissions('formSubmissions.read')
+  @ApiOperation({ summary: 'Return metadata for an uploaded file.' })
+  @ApiOkResponse({ description: 'Uploaded file metadata.', type: FileUploadResponseDto })
+  getMeta(
+    @Param('orgId') orgId: string,
+    @Param('fileId', ParseUUIDPipe) fileId: string,
+  ) {
+    return this.filesService.getMeta(orgId, fileId);
+  }
+}

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