@ftisindia/create-app 0.1.5 → 0.2.0

package/template/src/modules/audit/dto/audit-response.dto.ts

@@ -7,7 +7,7 @@ class AuditActorResponseDto {
   })
   id!: string;
 
-  @ApiPropertyOptional({ example: 'Starter Owner', nullable: true })
+  @ApiPropertyOptional({ type: String, example: 'Starter Owner', nullable: true })
   displayName?: string | null;
 }
 
@@ -19,6 +19,7 @@ export class AuditLogResponseDto {
   id!: string;
 
   @ApiPropertyOptional({
+    type: String,
     example: '2c67399d-670c-4025-a5fd-1ea9a211891e',
     format: 'uuid',
     nullable: true,
@@ -26,6 +27,7 @@ export class AuditLogResponseDto {
   orgId?: string | null;
 
   @ApiPropertyOptional({
+    type: String,
     example: '4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456',
     format: 'uuid',
     nullable: true,
@@ -39,6 +41,7 @@ export class AuditLogResponseDto {
   targetType!: string;
 
   @ApiPropertyOptional({
+    type: String,
     example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
     nullable: true,
   })
@@ -50,10 +53,10 @@ export class AuditLogResponseDto {
   })
   metadata?: Record<string, unknown> | null;
 
-  @ApiPropertyOptional({ example: '127.0.0.1', nullable: true })
+  @ApiPropertyOptional({ type: String, example: '127.0.0.1', nullable: true })
   ipAddress?: string | null;
 
-  @ApiPropertyOptional({ example: 'Mozilla/5.0', nullable: true })
+  @ApiPropertyOptional({ type: String, example: 'Mozilla/5.0', nullable: true })
   userAgent?: string | null;
 
   @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
@@ -68,6 +71,7 @@ export class AuditLogListResponseDto {
   items!: AuditLogResponseDto[];
 
   @ApiPropertyOptional({
+    type: String,
     example: 'df6537c4-f58b-452e-a67e-18ec528d0f0f',
     nullable: true,
   })

package/template/src/modules/auth/auth.module.ts

@@ -41,6 +41,8 @@ import { GoogleOAuthExceptionFilter } from './presentation/google-oauth-exceptio
     PasswordService,
     TokenService,
   ],
-  exports: [JwtAuthGuard, PasswordService],
+  // AuthService is exported for the forms module's delegating `authenticate`
+  // action (login-as-a-form rides the real auth stack, never reimplements it).
+  exports: [JwtAuthGuard, PasswordService, AuthService],
 })
 export class AuthModule {}

package/template/src/modules/auth/dto/auth-response.dto.ts

@@ -14,7 +14,7 @@ export class AuthTokensResponseDto {
   })
   refreshToken!: string;
 
-  @ApiProperty({ example: 'Bearer' })
+  @ApiProperty({ enum: ['Bearer'], example: 'Bearer' })
   tokenType!: 'Bearer';
 
   @ApiProperty({

package/template/src/modules/forms/application/services/file-gc.service.ts

@@ -0,0 +1,85 @@
+import { Injectable, Logger, OnApplicationBootstrap, OnModuleDestroy } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { isGcEligible } from '@ftisindia/form-builder';
+import { PrismaFileStore } from '../../infrastructure/stores/prisma-file.store';
+import { LocalDiskStorageAdapter } from '../../infrastructure/storage/local-disk-storage.adapter';
+
+const GC_BATCH_SIZE = 100;
+
+/**
+ * Sweeps orphaned TEMPORARY uploads (design doc §10.3): files uploaded but
+ * never linked to a submission within FORMS_FILE_TEMP_TTL_HOURS are deleted
+ * — bytes first, then the row. LINKED files are exempt by construction.
+ * runOnce() makes tests deterministic; the timer mirrors the outbox poller.
+ */
+@Injectable()
+export class FileGcService implements OnApplicationBootstrap, OnModuleDestroy {
+  private readonly logger = new Logger('FormsFileGc');
+  private timer?: NodeJS.Timeout;
+  private sweeping = false;
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly files: PrismaFileStore,
+    private readonly storage: LocalDiskStorageAdapter,
+  ) {}
+
+  onApplicationBootstrap(): void {
+    if (this.config.get<boolean>('forms.outboxEnabled') === false) {
+      // Test environments disable background work with one switch.
+      return;
+    }
+    const intervalMs = this.config.get<number>('forms.fileGcIntervalMs') ?? 3_600_000;
+    this.timer = setInterval(() => {
+      void this.sweep();
+    }, intervalMs);
+    this.timer.unref?.();
+  }
+
+  onModuleDestroy(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  async runOnce(now = new Date()): Promise<number> {
+    const ttlMs =
+      (this.config.get<number>('forms.fileTempTtlHours') ?? 24) * 60 * 60 * 1000;
+    const cutoff = new Date(now.getTime() - ttlMs);
+    const candidates = await this.files.listGcEligible(cutoff, GC_BATCH_SIZE);
+    let removed = 0;
+    for (const file of candidates) {
+      if (!isGcEligible(file, now, ttlMs)) {
+        continue;
+      }
+      try {
+        await this.storage.delete(file.storageKey);
+        await this.files.delete(file.id);
+        removed += 1;
+      } catch (error) {
+        this.logger.warn(
+          `Failed to garbage-collect file ${file.id}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    }
+    return removed;
+  }
+
+  private async sweep(): Promise<void> {
+    if (this.sweeping) {
+      return;
+    }
+    this.sweeping = true;
+    try {
+      const removed = await this.runOnce();
+      if (removed > 0) {
+        this.logger.log(`Garbage-collected ${removed} orphaned temporary file(s).`);
+      }
+    } catch (error) {
+      this.logger.error('File GC sweep failed.', error instanceof Error ? error.stack : error);
+    } finally {
+      this.sweeping = false;
+    }
+  }
+}

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

@@ -0,0 +1,137 @@
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { DataSourceRegistry, DefinitionService, walkFields } from '@ftisindia/form-builder';
+import type { DataSourceOption, FormDefinition } from '@ftisindia/form-builder';
+import { resolvePageLimit, toPage } from '../../../../common/dto/pagination-query.dto';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { CreateFormDefinitionDto } from '../../dto/create-form-definition.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';
+import { RequestFormsContext } from '../../infrastructure/request-forms-context';
+import { withFormsErrorMapping } from './forms-error.mapper';
+
+/**
+ * Thin HTTP-facing wrapper over the engine's DefinitionService: org-scope
+ * assertion first, engine call through the FormsContext seam, engine-typed
+ * errors mapped onto the app's HTTP envelope. No business logic lives here.
+ */
+@Injectable()
+export class FormsDefinitionsService {
+  constructor(
+    private readonly engine: DefinitionService,
+    private readonly dataSources: DataSourceRegistry,
+    private readonly formsContext: RequestFormsContext,
+    private readonly requestContext: RequestContextService,
+  ) {}
+
+  async list(orgId: string, query: ListFormDefinitionsQueryDto) {
+    this.requestContext.assertOrgScope(orgId);
+    const limit = resolvePageLimit(query.limit);
+
+    const records = await withFormsErrorMapping(() =>
+      this.engine.list(
+        { orgId, status: query.status, cursor: query.cursor, limit: limit + 1 },
+        this.formsContext,
+      ),
+    );
+
+    return toPage(records, limit);
+  }
+
+  async create(orgId: string, dto: CreateFormDefinitionDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.createDraft(
+        { orgId, definition: dto.definition as unknown as FormDefinition },
+        this.formsContext,
+      ),
+    );
+  }
+
+  async getLatest(orgId: string, formKey: string) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.getLatest({ orgId, key: formKey }, this.formsContext),
+    );
+  }
+
+  async getVersion(orgId: string, formKey: string, version: number) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.getByKeyVersion({ orgId, key: formKey, version }, this.formsContext),
+    );
+  }
+
+  async update(orgId: string, formKey: string, version: number, dto: UpdateFormDefinitionDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.updateDraft(
+        {
+          orgId,
+          key: formKey,
+          version,
+          definition: dto.definition as unknown as FormDefinition,
+        },
+        this.formsContext,
+      ),
+    );
+  }
+
+  async publish(orgId: string, formKey: string, version: number) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.publish({ orgId, key: formKey, version }, this.formsContext),
+    );
+  }
+
+  async archive(orgId: string, formKey: string, version: number) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.archive({ orgId, key: formKey, version }, this.formsContext),
+    );
+  }
+
+  async setPublicAccess(orgId: string, formKey: string, version: number, dto: SetPublicAccessDto) {
+    this.requestContext.assertOrgScope(orgId);
+    return withFormsErrorMapping(() =>
+      this.engine.setPublicAccess(
+        { orgId, key: formKey, version, access: dto.access },
+        this.formsContext,
+      ),
+    );
+  }
+
+  async render(orgId: string, formKey: string) {
+    this.requestContext.assertOrgScope(orgId);
+    const result = await withFormsErrorMapping(() =>
+      this.engine.getForRender({ orgId, key: formKey }, this.formsContext),
+    );
+    return { definition: result.definition, options: result.options };
+  }
+
+  async dataSourceOptions(orgId: string, formKey: string, dataSourceKey: string) {
+    this.requestContext.assertOrgScope(orgId);
+    const render = await withFormsErrorMapping(() =>
+      this.engine.getForRender({ orgId, key: formKey }, this.formsContext),
+    );
+
+    const paths: string[] = [];
+    walkFields(render.definition.fields, (field, path) => {
+      if (field.dataSource?.key === dataSourceKey) {
+        paths.push(path.join('.'));
+      }
+    });
+
+    if (paths.length === 0) {
+      throw new NotFoundException('No field on this form uses the requested data source.');
+    }
+
+    const items: DataSourceOption[] = paths.flatMap((path) => render.options[path] ?? []);
+    return { items };
+  }
+
+  listDataSourceKeys(orgId: string) {
+    this.requestContext.assertOrgScope(orgId);
+    return { items: this.dataSources.keys() };
+  }
+}

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

@@ -0,0 +1,64 @@
+import {
+  ConflictException,
+  ForbiddenException,
+  NotFoundException,
+  UnprocessableEntityException,
+} from '@nestjs/common';
+import {
+  FormsAuthzDeniedError,
+  FormsConflictError,
+  FormsDefinitionLintError,
+  FormsNotFoundError,
+  FormsStateError,
+  FormsValidationError,
+} from '@ftisindia/form-builder';
+import { Prisma } from '@prisma/client';
+
+/**
+ * Maps the engine's typed errors (ecosystem guide §2.1) onto the app's HTTP
+ * error envelope. Object bodies survive the global HttpExceptionFilter, which
+ * lifts every non-message key into `error.details` — so 422 responses carry
+ * the engine's `errors` / `issues` arrays verbatim.
+ */
+export function mapFormsError(error: unknown): never {
+  if (error instanceof FormsValidationError) {
+    throw new UnprocessableEntityException({
+      message: 'Validation failed.',
+      errors: error.errors,
+    });
+  }
+
+  if (error instanceof FormsDefinitionLintError) {
+    throw new UnprocessableEntityException({
+      message: 'Form definition is invalid.',
+      issues: error.issues,
+    });
+  }
+
+  if (error instanceof FormsAuthzDeniedError) {
+    throw new ForbiddenException(error.message);
+  }
+
+  if (error instanceof FormsNotFoundError) {
+    throw new NotFoundException(error.message);
+  }
+
+  if (error instanceof FormsConflictError || error instanceof FormsStateError) {
+    throw new ConflictException(error.message);
+  }
+
+  if (error instanceof Prisma.PrismaClientKnownRequestError && error.code === 'P2002') {
+    throw new ConflictException('A form definition with this key and version already exists.');
+  }
+
+  throw error;
+}
+
+/** Awaits an engine call and maps any engine-typed failure onto HTTP errors. */
+export async function withFormsErrorMapping<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (error) {
+    mapFormsError(error);
+  }
+}

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

@@ -0,0 +1,210 @@
+import { ForbiddenException, Injectable, NotFoundException } from '@nestjs/common';
+import { FieldTypeRegistry } from '@ftisindia/form-builder';
+import type { FieldDef, FormDefinition, SubmissionRecord } from '@ftisindia/form-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { AuditService } from '../../../audit/application/services/audit.service';
+import { AuthenticatedUser } from '../../../auth/types/authenticated-user';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { ExportSubmissionsQueryDto } from '../../dto/export-submissions-query.dto';
+import { PrismaFormDefinitionStore } from '../../infrastructure/stores/prisma-form-definition.store';
+import { PrismaSubmissionStore } from '../../infrastructure/stores/prisma-submission.store';
+
+const BASE_COLUMNS = ['id', 'formVersion', 'status', 'createdBy', 'createdAt'] as const;
+
+export interface ExportResult {
+  format: 'csv' | 'json';
+  columns: string[];
+  rows: Array<Record<string, unknown>>;
+  csv?: string;
+}
+
+/**
+ * Submission export — PII egress, treated accordingly (ecosystem guide §7):
+ * gated by formSubmissions.export (never implied by .read at the route), and
+ * EVERY export writes an audit row recording form key, filters, row count,
+ * and included fields — including empty results. Field selection defaults to
+ * the definitions' `reportable` manifest (design doc §15), computed
+ * version-aware across the versions present in the result set; sensitive and
+ * credential-typed fields are refused even when requested explicitly.
+ */
+@Injectable()
+export class FormsExportService {
+  constructor(
+    private readonly definitions: PrismaFormDefinitionStore,
+    private readonly submissions: PrismaSubmissionStore,
+    private readonly audit: AuditService,
+    private readonly prisma: PrismaService,
+    private readonly requestContext: RequestContextService,
+    private readonly fieldTypes: FieldTypeRegistry,
+  ) {}
+
+  async export(
+    orgId: string,
+    formKey: string,
+    query: ExportSubmissionsQueryDto,
+    user: AuthenticatedUser,
+  ): Promise<ExportResult> {
+    this.requestContext.assertOrgScope(orgId);
+
+    const latest = await this.definitions.findLatest(orgId, formKey);
+    if (!latest) {
+      throw new NotFoundException('Form was not found.');
+    }
+
+    const filters = {
+      status: query.status,
+      createdFrom: query.from ? new Date(query.from) : undefined,
+      createdTo: query.to ? new Date(query.to) : undefined,
+    };
+    const rows = await this.submissions.listForExport(orgId, formKey, filters);
+
+    const versions = [...new Set([latest.version, ...rows.map((row) => row.formVersion)])];
+    const schemas: FormDefinition[] = [latest.schema];
+    for (const version of versions) {
+      if (version === latest.version) {
+        continue;
+      }
+      const record = await this.definitions.findByKeyVersion(orgId, formKey, version);
+      if (record) {
+        schemas.push(record.schema);
+      }
+    }
+
+    const { reportable, sensitive } = this.fieldManifest(schemas);
+    const requested = query.fields
+      ? query.fields.split(',').map((field) => field.trim()).filter(Boolean)
+      : undefined;
+    if (requested) {
+      const refused = requested.filter((field) => sensitive.has(field));
+      if (refused.length > 0) {
+        throw new ForbiddenException(
+          `Sensitive fields can never be exported: ${refused.join(', ')}.`,
+        );
+      }
+    }
+    const dataColumns = (requested ?? [...reportable]).filter((field) => !sensitive.has(field));
+    const columns = [...BASE_COLUMNS, ...dataColumns];
+
+    const flatRows = rows.map((row) => this.flatten(row, dataColumns));
+    const format = query.format ?? 'json';
+    const result: ExportResult = { format, columns, rows: flatRows };
+    if (format === 'csv') {
+      result.csv = this.toCsv(columns, flatRows);
+    }
+
+    await this.audit.write(this.prisma, {
+      orgId,
+      actorUserId: user.id,
+      action: 'formSubmissions.export',
+      targetType: 'FormDefinition',
+      targetId: latest.id,
+      metadata: {
+        formKey,
+        filters: {
+          status: query.status ?? null,
+          from: query.from ?? null,
+          to: query.to ?? null,
+        },
+        rowCount: rows.length,
+        fields: dataColumns,
+        format,
+      },
+    });
+
+    return result;
+  }
+
+  /** Version-aware union of reportable field names; sensitive set across ALL versions. */
+  private fieldManifest(schemas: FormDefinition[]) {
+    const reportable = new Set<string>();
+    const sensitive = new Set<string>();
+    for (const schema of schemas) {
+      this.collectFieldManifest(schema.fields, [], false, reportable, sensitive);
+    }
+    return { reportable, sensitive };
+  }
+
+  private collectFieldManifest(
+    fields: FieldDef[],
+    parentPath: string[],
+    inheritedSensitive: boolean,
+    reportable: Set<string>,
+    sensitive: Set<string>,
+  ): boolean {
+    let subtreeHasSensitive = false;
+    for (const field of fields) {
+      const path = [...parentPath, field.name];
+      const dotted = path.join('.');
+      const ownSensitive = inheritedSensitive || this.isSensitiveField(field);
+      if (field.reportable === true) {
+        reportable.add(dotted);
+      }
+
+      const childHasSensitive =
+        field.fields && field.fields.length > 0
+          ? this.collectFieldManifest(
+              field.fields,
+              path,
+              ownSensitive,
+              reportable,
+              sensitive,
+            )
+          : false;
+
+      if (ownSensitive || childHasSensitive) {
+        sensitive.add(dotted);
+        sensitive.add(field.name);
+        subtreeHasSensitive = true;
+      }
+    }
+    return subtreeHasSensitive;
+  }
+
+  private isSensitiveField(field: FieldDef): boolean {
+    return field.sensitive === true || this.fieldTypes.get(field.type)?.alwaysSensitive === true;
+  }
+
+  private flatten(row: SubmissionRecord, dataColumns: string[]): Record<string, unknown> {
+    const flat: Record<string, unknown> = {
+      id: row.id,
+      formVersion: row.formVersion,
+      status: row.status,
+      createdBy: row.createdBy ?? null,
+      createdAt: row.createdAt.toISOString(),
+    };
+    for (const column of dataColumns) {
+      const value = this.valueAtPath(row.data, column);
+      flat[column] =
+        value !== null && typeof value === 'object' ? JSON.stringify(value) : (value ?? null);
+    }
+    return flat;
+  }
+
+  private valueAtPath(data: Record<string, unknown>, dotted: string): unknown {
+    let current: unknown = data;
+    for (const segment of dotted.split('.')) {
+      if (current === null || typeof current !== 'object' || Array.isArray(current)) {
+        return undefined;
+      }
+      current = (current as Record<string, unknown>)[segment];
+    }
+    return current;
+  }
+
+  private toCsv(columns: string[], rows: Array<Record<string, unknown>>): string {
+    const escape = (value: unknown): string => {
+      if (value === null || value === undefined) {
+        return '';
+      }
+      // flatten() already stringifies objects; this branch is type-level only.
+      const text =
+        typeof value === 'object' ? JSON.stringify(value) : String(value as string | number);
+      return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+    };
+    const lines = [columns.map(escape).join(',')];
+    for (const row of rows) {
+      lines.push(columns.map((column) => escape(row[column])).join(','));
+    }
+    return lines.join('\r\n');
+  }
+}