@ftisindia/create-app 0.1.5 → 0.2.0

package/template/src/modules/forms/dto/list-form-definitions-query.dto.ts

@@ -0,0 +1,10 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn, IsOptional } from 'class-validator';
+import { PaginationQueryDto } from '../../../common/dto/pagination-query.dto';
+
+export class ListFormDefinitionsQueryDto extends PaginationQueryDto {
+  @ApiPropertyOptional({ enum: ['DRAFT', 'PUBLISHED', 'ARCHIVED'] })
+  @IsOptional()
+  @IsIn(['DRAFT', 'PUBLISHED', 'ARCHIVED'])
+  status?: 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
+}

package/template/src/modules/forms/dto/list-submissions-query.dto.ts

@@ -0,0 +1,10 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn, IsOptional } from 'class-validator';
+import { PaginationQueryDto } from '../../../common/dto/pagination-query.dto';
+
+export class ListSubmissionsQueryDto extends PaginationQueryDto {
+  @ApiPropertyOptional({ enum: ['DRAFT', 'SUBMITTED'] })
+  @IsOptional()
+  @IsIn(['DRAFT', 'SUBMITTED'])
+  status?: 'DRAFT' | 'SUBMITTED';
+}

package/template/src/modules/forms/dto/public-submit-form.dto.ts

@@ -0,0 +1,24 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsInt, IsObject, IsOptional, IsString, MaxLength, Min } from 'class-validator';
+
+export class PublicSubmitFormDto {
+  @ApiProperty({
+    type: 'object',
+    additionalProperties: true,
+    description: 'The submission payload, validated against the form definition.',
+  })
+  @IsObject()
+  data!: Record<string, unknown>;
+
+  @ApiPropertyOptional({ description: 'Specific definition version; defaults to latest published.' })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  version?: number;
+
+  @ApiPropertyOptional({ description: 'Captcha token, required when the form enables captcha.' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(4096)
+  captchaToken?: string;
+}

package/template/src/modules/forms/dto/set-public-access.dto.ts

@@ -0,0 +1,8 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsIn } from 'class-validator';
+
+export class SetPublicAccessDto {
+  @ApiProperty({ enum: ['public', 'private'], example: 'private' })
+  @IsIn(['public', 'private'])
+  access!: 'public' | 'private';
+}

package/template/src/modules/forms/dto/submission-response.dto.ts

@@ -0,0 +1,99 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class SubmissionResponseDto {
+  @ApiProperty({
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+  })
+  id!: string;
+
+  @ApiProperty({
+    example: '2c67399d-670c-4025-a5fd-1ea9a211891e',
+    format: 'uuid',
+  })
+  orgId!: string;
+
+  @ApiProperty({ example: 'abstract-submission' })
+  formKey!: string;
+
+  @ApiProperty({ example: 1, description: 'The definition version the data was captured under.' })
+  formVersion!: number;
+
+  @ApiProperty({ type: 'object', additionalProperties: true })
+  data!: Record<string, unknown>;
+
+  @ApiProperty({ enum: ['DRAFT', 'SUBMITTED'], example: 'SUBMITTED' })
+  status!: 'DRAFT' | 'SUBMITTED';
+
+  @ApiProperty({ example: false })
+  locked!: boolean;
+
+  @ApiPropertyOptional({
+    type: String,
+    example: '4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456',
+    format: 'uuid',
+    nullable: true,
+  })
+  createdBy?: string | null;
+
+  @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
+  createdAt!: string;
+
+  @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
+  updatedAt!: string;
+}
+
+export class SubmissionListResponseDto {
+  @ApiProperty({ type: [SubmissionResponseDto] })
+  items!: SubmissionResponseDto[];
+
+  @ApiPropertyOptional({
+    type: String,
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+    nullable: true,
+  })
+  nextCursor!: string | null;
+}
+
+export class SubmitResultResponseDto {
+  @ApiProperty({
+    type: String,
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+    nullable: true,
+  })
+  submissionId!: string | null;
+
+  @ApiProperty({
+    type: 'object',
+    additionalProperties: true,
+    description: 'Outputs of every executed action, keyed by action name.',
+  })
+  outputs!: Record<string, unknown>;
+}
+
+export class ValidationErrorItemDto {
+  @ApiProperty({
+    example: 'authors.0.email',
+    description: 'Dotted data path. Empty string means the whole document.',
+  })
+  path!: string;
+
+  @ApiProperty({ example: 'REQUIRED' })
+  code!: string;
+
+  @ApiProperty({ example: 'This field is required.' })
+  message!: string;
+
+  @ApiPropertyOptional({ example: 'require-corresponding-author' })
+  ruleId?: string;
+}
+
+export class ValidationResultResponseDto {
+  @ApiProperty({ example: false })
+  valid!: boolean;
+
+  @ApiProperty({ type: [ValidationErrorItemDto] })
+  errors!: ValidationErrorItemDto[];
+}

package/template/src/modules/forms/dto/submit-form.dto.ts

@@ -0,0 +1,50 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  IsIn,
+  IsInt,
+  IsObject,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+  Min,
+} from 'class-validator';
+
+export class SubmitFormDto {
+  @ApiProperty({ enum: ['draft', 'submit'], example: 'submit' })
+  @IsIn(['draft', 'submit'])
+  mode!: 'draft' | 'submit';
+
+  @ApiPropertyOptional({
+    example: 'submit',
+    maxLength: 64,
+    description: 'Button name in the definition actions map. Defaults to the mode.',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(64)
+  button?: string;
+
+  @ApiPropertyOptional({
+    example: 3,
+    minimum: 1,
+    description: 'Specific definition version; defaults to the latest published one.',
+  })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  version?: number;
+
+  @ApiProperty({ type: 'object', additionalProperties: true })
+  @IsObject()
+  data!: Record<string, unknown>;
+
+  @ApiPropertyOptional({
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+    description: 'Present when editing an existing draft submission.',
+  })
+  @IsOptional()
+  @IsUUID()
+  submissionId?: string;
+}

package/template/src/modules/forms/dto/update-form-definition.dto.ts

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsObject } from 'class-validator';
+
+export class UpdateFormDefinitionDto {
+  @ApiProperty({
+    type: 'object',
+    additionalProperties: true,
+    description: 'The FormDefinition document (validated against the engine meta-schema).',
+  })
+  @IsObject()
+  definition!: Record<string, unknown>;
+}

package/template/src/modules/forms/dto/upload-file-query.dto.ts

@@ -0,0 +1,33 @@
+import { Type } from 'class-transformer';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsInt, IsOptional, IsString, IsUUID, MaxLength, Min } from 'class-validator';
+
+export class UploadFileQueryDto {
+  @ApiProperty({
+    description: 'File field name in the target form definition.',
+    example: 'manuscript',
+  })
+  @IsString()
+  @MaxLength(128)
+  field!: string;
+
+  @ApiPropertyOptional({
+    example: 3,
+    minimum: 1,
+    description: 'Specific definition version; defaults to the latest published one.',
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  version?: number;
+
+  @ApiPropertyOptional({
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+    description: 'Existing draft submission whose form version should be used.',
+  })
+  @IsOptional()
+  @IsUUID()
+  submissionId?: string;
+}

package/template/src/modules/forms/dto/validate-submission.dto.ts

@@ -0,0 +1,22 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn, IsInt, IsObject, IsOptional, Min } from 'class-validator';
+
+export class ValidateSubmissionDto {
+  @ApiProperty({ enum: ['draft', 'submit'], example: 'submit' })
+  @IsIn(['draft', 'submit'])
+  mode!: 'draft' | 'submit';
+
+  @ApiPropertyOptional({
+    example: 3,
+    minimum: 1,
+    description: 'Specific definition version; defaults to the latest published one.',
+  })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  version?: number;
+
+  @ApiProperty({ type: 'object', additionalProperties: true })
+  @IsObject()
+  data!: Record<string, unknown>;
+}

package/template/src/modules/forms/examples/abstract-submission.form.json

@@ -0,0 +1,80 @@
+{
+  "key": "abstract-submission",
+  "version": 1,
+  "title": "Scientific abstract submission",
+  "fields": [
+    {
+      "type": "text",
+      "name": "title",
+      "label": "Abstract title",
+      "validators": { "required": true, "maxLength": 200 },
+      "reportable": true
+    },
+    {
+      "type": "group",
+      "name": "authors",
+      "label": "Authors",
+      "repeatable": true,
+      "min": 1,
+      "max": 10,
+      "fields": [
+        { "type": "text", "name": "fullName", "validators": { "required": true } },
+        { "type": "email", "name": "email", "validators": { "required": true } },
+        { "type": "boolean", "name": "isPresenting" }
+      ]
+    },
+    {
+      "type": "select",
+      "name": "track",
+      "label": "Conference track",
+      "dataSource": { "key": "conference-tracks" },
+      "validators": { "required": true },
+      "reportable": true,
+      "indexHint": true
+    },
+    {
+      "type": "text",
+      "name": "body",
+      "label": "Abstract body",
+      "validators": { "required": true, "maxLength": 3000 },
+      "ui": { "widget": "richtext" }
+    },
+    {
+      "type": "file",
+      "name": "manuscript",
+      "label": "Full manuscript (PDF)",
+      "accept": ["application/pdf"],
+      "maxSizeMb": 20
+    },
+    {
+      "type": "boolean",
+      "name": "needsFunding",
+      "label": "Requesting funding?"
+    },
+    {
+      "type": "text",
+      "name": "fundingSource",
+      "label": "Funding source",
+      "ui": { "showWhen": "needsFunding" }
+    },
+    {
+      "type": "hidden",
+      "name": "submittedBy",
+      "source": "context",
+      "path": "user.id"
+    }
+  ],
+  "rules": [
+    {
+      "id": "funding-required",
+      "enforceOn": ["submit"],
+      "if": { "==": [{ "var": "data.needsFunding" }, true] },
+      "then": { "require": ["fundingSource"] },
+      "message": "Funding source is required when requesting funding."
+    }
+  ],
+  "actions": {
+    "submit": ["validateAll", "persist", "lockEditing", "sendConfirmationEmail"],
+    "saveDraft": ["persistDraft"]
+  }
+}

package/template/src/modules/forms/examples/login.form.json

@@ -0,0 +1,24 @@
+{
+  "key": "login",
+  "version": 1,
+  "title": "Sign in",
+  "settings": { "access": "public" },
+  "fields": [
+    {
+      "type": "email",
+      "name": "email",
+      "label": "Email address",
+      "validators": { "required": true }
+    },
+    {
+      "type": "password",
+      "name": "password",
+      "label": "Password",
+      "validators": { "required": true, "minLength": 8 },
+      "ui": { "widget": "password" }
+    }
+  ],
+  "actions": {
+    "submit": ["authenticate"]
+  }
+}

package/template/src/modules/forms/examples/registration.form.json

@@ -0,0 +1,44 @@
+{
+  "key": "registration",
+  "version": 1,
+  "title": "Event registration",
+  "fields": [
+    {
+      "type": "text",
+      "name": "fullName",
+      "label": "Full name",
+      "validators": { "required": true, "maxLength": 120 },
+      "reportable": true
+    },
+    {
+      "type": "email",
+      "name": "email",
+      "label": "Email address",
+      "validators": { "required": true },
+      "reportable": true,
+      "indexHint": true
+    },
+    {
+      "type": "select",
+      "name": "ticketType",
+      "label": "Ticket type",
+      "validators": { "required": true, "options": ["standard", "student", "vip"] },
+      "reportable": true
+    },
+    {
+      "type": "boolean",
+      "name": "newsletter",
+      "label": "Subscribe to updates?"
+    },
+    {
+      "type": "hidden",
+      "name": "registeredBy",
+      "source": "context",
+      "path": "user.id"
+    }
+  ],
+  "actions": {
+    "submit": ["validateAll", "persist", "sendConfirmationEmail"],
+    "saveDraft": ["persistDraft"]
+  }
+}

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

@@ -0,0 +1,228 @@
+import { Module } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import {
+  ActionRegistry,
+  DataSourceRegistry,
+  DataSourceResolver,
+  DefinitionService,
+  FieldTypeRegistry,
+  LifecycleRegistry,
+  OutboxHandlerRegistry,
+  SubmissionService,
+  ValidationEngine,
+  registerCoreFieldTypes,
+} from '@ftisindia/form-builder';
+import { AuthModule } from '../auth/auth.module';
+import { FileGcService } from './application/services/file-gc.service';
+import { FormsDefinitionsService } from './application/services/forms-definitions.service';
+import { FormsExportService } from './application/services/forms-export.service';
+import { FormsFilesService } from './application/services/forms-files.service';
+import { FormsPublicService } from './application/services/forms-public.service';
+import { FormsSettingsReader } from './application/services/forms-settings-reader.service';
+import { FormsSubmissionsService } from './application/services/forms-submissions.service';
+import { AuthenticateActionHandler } from './application/services/handlers/authenticate.action';
+import { LoggingEmailHandler } from './application/services/handlers/logging-email.handler';
+import { SendConfirmationEmailAction } from './application/services/handlers/send-confirmation-email.action';
+import { WebhookOutboxHandler } from './application/services/handlers/webhook.handler';
+import { OutboxDispatcherService } from './application/services/outbox-dispatcher.service';
+import { CaslFormsAuthorization } from './infrastructure/casl-forms-authorization';
+import { PrismaFormsAuditSink } from './infrastructure/audit-sink.adapter';
+import { PrismaTxRunner } from './infrastructure/prisma-tx-runner';
+import { RequestFormsContext } from './infrastructure/request-forms-context';
+import { RegistryBootstrapService } from './infrastructure/registry/registry-bootstrap.service';
+import { FormsSchemaCheckService } from './infrastructure/schema-check/forms-schema-check.service';
+import { LocalDiskStorageAdapter } from './infrastructure/storage/local-disk-storage.adapter';
+import { PrismaActionLogStore } from './infrastructure/stores/prisma-action-log.store';
+import { PrismaFileStore } from './infrastructure/stores/prisma-file.store';
+import { PrismaFormDefinitionStore } from './infrastructure/stores/prisma-form-definition.store';
+import { PrismaOutboxStore } from './infrastructure/stores/prisma-outbox.store';
+import { PrismaSubmissionStore } from './infrastructure/stores/prisma-submission.store';
+import { FormsDataSourcesController } from './presentation/forms-data-sources.controller';
+import { FormsDefinitionsController } from './presentation/forms-definitions.controller';
+import { FormsFilesController } from './presentation/forms-files.controller';
+import { FormsSubmissionsController } from './presentation/forms-submissions.controller';
+import { FormsUploadInterceptor } from './presentation/forms-upload.interceptor';
+import { PublicFormsController } from './presentation/public-forms.controller';
+import { FORMS_CAPTCHA_VERIFIER } from './forms.tokens';
+
+/**
+ * The forms glue module — the ONLY place that binds the framework-free
+ * @ftisindia/form-builder engine to this app's services (request context,
+ * CASL RBAC, AuditService, Prisma). Engine services are composed here via
+ * factories over the four adapters and five stores; app extensions register
+ * through the @FormFieldType/@FormActionHandler/@FormDataSource decorators.
+ */
+@Module({
+  imports: [AuthModule, DiscoveryModule],
+  controllers: [
+    // Listed before the definitions controller so the literal 'data-sources'
+    // segment wins over the ':formKey' parameter on the shared base path.
+    FormsDataSourcesController,
+    FormsDefinitionsController,
+    FormsFilesController,
+    FormsSubmissionsController,
+    PublicFormsController,
+  ],
+  providers: [
+    // Adapters over the ecosystem seams.
+    RequestFormsContext,
+    CaslFormsAuthorization,
+    PrismaFormsAuditSink,
+    PrismaTxRunner,
+    // Prisma store implementations of the engine ports.
+    PrismaFormDefinitionStore,
+    PrismaSubmissionStore,
+    PrismaOutboxStore,
+    PrismaFileStore,
+    PrismaActionLogStore,
+    FormsSettingsReader,
+    { provide: FORMS_CAPTCHA_VERIFIER, useValue: undefined },
+    // Engine registries — singletons; core field types registered up front.
+    {
+      provide: FieldTypeRegistry,
+      useFactory: () => {
+        const registry = new FieldTypeRegistry();
+        registerCoreFieldTypes(registry);
+        return registry;
+      },
+    },
+    { provide: ActionRegistry, useFactory: () => new ActionRegistry() },
+    { provide: DataSourceRegistry, useFactory: () => new DataSourceRegistry() },
+    { provide: LifecycleRegistry, useFactory: () => new LifecycleRegistry() },
+    { provide: OutboxHandlerRegistry, useFactory: () => new OutboxHandlerRegistry() },
+    {
+      provide: ValidationEngine,
+      useFactory: (fieldTypes: FieldTypeRegistry) => new ValidationEngine(fieldTypes),
+      inject: [FieldTypeRegistry],
+    },
+    {
+      provide: DataSourceResolver,
+      useFactory: (dataSources: DataSourceRegistry) => new DataSourceResolver(dataSources),
+      inject: [DataSourceRegistry],
+    },
+    // Engine orchestration services, composed over the adapters and stores.
+    {
+      provide: DefinitionService,
+      useFactory: (
+        store: PrismaFormDefinitionStore,
+        authz: CaslFormsAuthorization,
+        audit: PrismaFormsAuditSink,
+        txRunner: PrismaTxRunner,
+        fieldTypes: FieldTypeRegistry,
+        actions: ActionRegistry,
+        dataSources: DataSourceRegistry,
+        resolver: DataSourceResolver,
+        settings: FormsSettingsReader,
+      ) =>
+        new DefinitionService({
+          store,
+          authz,
+          audit,
+          txRunner,
+          fieldTypes,
+          actions,
+          dataSources,
+          resolver,
+          policyFor: (orgId) => settings.policyFor(orgId),
+        }),
+      inject: [
+        PrismaFormDefinitionStore,
+        CaslFormsAuthorization,
+        PrismaFormsAuditSink,
+        PrismaTxRunner,
+        FieldTypeRegistry,
+        ActionRegistry,
+        DataSourceRegistry,
+        DataSourceResolver,
+        FormsSettingsReader,
+      ],
+    },
+    {
+      provide: SubmissionService,
+      useFactory: (
+        definitions: PrismaFormDefinitionStore,
+        submissions: PrismaSubmissionStore,
+        files: PrismaFileStore,
+        outbox: PrismaOutboxStore,
+        actionLog: PrismaActionLogStore,
+        audit: PrismaFormsAuditSink,
+        txRunner: PrismaTxRunner,
+        authz: CaslFormsAuthorization,
+        fieldTypes: FieldTypeRegistry,
+        actions: ActionRegistry,
+        lifecycles: LifecycleRegistry,
+        validation: ValidationEngine,
+        resolver: DataSourceResolver,
+        settings: FormsSettingsReader,
+      ) =>
+        new SubmissionService({
+          definitions,
+          submissions,
+          files,
+          outbox,
+          actionLog,
+          audit,
+          txRunner,
+          authz,
+          fieldTypes,
+          actions,
+          lifecycles,
+          validation,
+          resolver,
+          captcha: settings.captchaVerifier,
+          policyFor: (orgId) => settings.policyFor(orgId),
+        }),
+      inject: [
+        PrismaFormDefinitionStore,
+        PrismaSubmissionStore,
+        PrismaFileStore,
+        PrismaOutboxStore,
+        PrismaActionLogStore,
+        PrismaFormsAuditSink,
+        PrismaTxRunner,
+        CaslFormsAuthorization,
+        FieldTypeRegistry,
+        ActionRegistry,
+        LifecycleRegistry,
+        ValidationEngine,
+        DataSourceResolver,
+        FormsSettingsReader,
+      ],
+    },
+    // Startup wiring + background work.
+    RegistryBootstrapService,
+    FormsSchemaCheckService,
+    OutboxDispatcherService,
+    LocalDiskStorageAdapter,
+    FileGcService,
+    FormsUploadInterceptor,
+    // Default outbox handlers + shipped form actions.
+    LoggingEmailHandler,
+    WebhookOutboxHandler,
+    AuthenticateActionHandler,
+    SendConfirmationEmailAction,
+    // Thin HTTP-facing services.
+    FormsDefinitionsService,
+    FormsSubmissionsService,
+    FormsFilesService,
+    FormsPublicService,
+    FormsExportService,
+  ],
+  exports: [
+    FieldTypeRegistry,
+    ActionRegistry,
+    DataSourceRegistry,
+    LifecycleRegistry,
+    OutboxHandlerRegistry,
+    OutboxDispatcherService,
+    // Consumed ONLY by the optional ReportsFormsModule bridge (report design
+    // §3.2/§13): the form definition store backs the form→report source
+    // adapter, and SubmissionService + the forms request context let the
+    // delegated editSubmission/updateStatus grid verbs run the form engine's
+    // own validation pipeline. ReportsModule itself imports none of this.
+    PrismaFormDefinitionStore,
+    SubmissionService,
+    RequestFormsContext,
+  ],
+})
+export class FormsModule {}

package/template/src/modules/forms/forms.tokens.ts

@@ -0,0 +1,6 @@
+/**
+ * Optional-provider tokens for the forms module's seams. Bind an
+ * implementation in your AppModule to activate the seam; absence fails
+ * closed (e.g. captcha-enabled definitions refuse to publish).
+ */
+export const FORMS_CAPTCHA_VERIFIER = 'FORMS_CAPTCHA_VERIFIER';