@ftisindia/create-app 0.1.4 → 0.1.6

package/template/src/modules/forms/application/services/handlers/webhook.handler.ts

@@ -0,0 +1,41 @@
+import { createHmac } from 'node:crypto';
+import { Injectable } from '@nestjs/common';
+import type { OutboxJobHandler, OutboxJobRecord } from '@ftisindia/form-builder';
+
+/**
+ * Generic webhook delivery. Payload contract: { url: string, body?: object,
+ * secret?: string }. When a secret is set, the request carries
+ * `x-forms-signature: sha256=<hmac-sha256(rawBody)>` so receivers can verify
+ * authenticity. Non-2xx responses and timeouts throw, which the dispatcher
+ * turns into a retry with backoff (then parks as FAILED after max attempts).
+ */
+@Injectable()
+export class WebhookOutboxHandler implements OutboxJobHandler {
+  readonly type = 'webhook';
+
+  async handle(job: OutboxJobRecord): Promise<void> {
+    const { url, body, secret } = job.payload as {
+      url?: unknown;
+      body?: unknown;
+      secret?: unknown;
+    };
+    if (typeof url !== 'string' || url.length === 0) {
+      throw new Error('Webhook job payload requires a "url" string.');
+    }
+    const rawBody = JSON.stringify(body ?? {});
+    const headers: Record<string, string> = { 'content-type': 'application/json' };
+    if (typeof secret === 'string' && secret.length > 0) {
+      headers['x-forms-signature'] =
+        'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex');
+    }
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: rawBody,
+      signal: AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+      throw new Error(`Webhook endpoint responded with status ${response.status}.`);
+    }
+  }
+}

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

@@ -0,0 +1,109 @@
+import { Injectable, Logger, OnApplicationBootstrap, OnModuleDestroy } from '@nestjs/common';
+import { ConfigService } from '@nestjs/config';
+import { OutboxHandlerRegistry, runDispatchCycle } from '@ftisindia/form-builder';
+import type { DispatchCycleResult } from '@ftisindia/form-builder';
+import { PrismaService } from '../../../../database/prisma/prisma.service';
+import { AuditService } from '../../../audit/application/services/audit.service';
+import { RequestContextService } from '../../../request-context/application/services/request-context.service';
+import { PrismaOutboxStore } from '../../infrastructure/stores/prisma-outbox.store';
+
+/**
+ * In-process outbox poller (ecosystem guide §3/§8.3). Every claimed job runs
+ * inside requestContext.run({ source: 'worker', jobId, orgId, userId,
+ * requestId: originRequestId }) so audit and logging keep working in
+ * background work and every external side effect stays traceable to its
+ * originating request. Successful delivery writes an audit row.
+ *
+ * Deterministic in tests: FORMS_OUTBOX_ENABLED=false disables the timer and
+ * runOnce() drives a single cycle by hand. Single-instance by design — a
+ * multi-node deployment should swap the store's claim for SKIP LOCKED or a
+ * real queue (BullMQ) without touching the engine.
+ */
+@Injectable()
+export class OutboxDispatcherService implements OnApplicationBootstrap, OnModuleDestroy {
+  private readonly logger = new Logger('FormsOutbox');
+  private timer?: NodeJS.Timeout;
+  private ticking = false;
+
+  constructor(
+    private readonly config: ConfigService,
+    private readonly store: PrismaOutboxStore,
+    private readonly handlers: OutboxHandlerRegistry,
+    private readonly requestContext: RequestContextService,
+    private readonly audit: AuditService,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  onApplicationBootstrap(): void {
+    if (this.config.get<boolean>('forms.outboxEnabled') === false) {
+      return;
+    }
+    const pollMs = this.config.get<number>('forms.outboxPollMs') ?? 5000;
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, pollMs);
+    this.timer.unref?.();
+  }
+
+  onModuleDestroy(): void {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  async runOnce(): Promise<DispatchCycleResult> {
+    return runDispatchCycle(this.store, this.handlers, {
+      wrapJob: (job, run) =>
+        this.requestContext.run(
+          {
+            source: 'worker',
+            jobId: job.id,
+            orgId: job.orgId ?? undefined,
+            userId: job.actorUserId ?? undefined,
+            requestId: job.originRequestId ?? undefined,
+          },
+          async () => {
+            const outcome = await run();
+            if (outcome === 'done') {
+              try {
+                await this.audit.write(this.prisma, {
+                  orgId: job.orgId ?? null,
+                  actorUserId: job.actorUserId ?? null,
+                  action: 'forms.outbox.delivered',
+                  targetType: 'FormOutboxJob',
+                  targetId: job.id,
+                  metadata: { type: job.type, attempts: job.attempts + 1 },
+                });
+              } catch (error) {
+                this.logger.warn(
+                  `Outbox delivery audit failed for job ${job.id}.`,
+                  error instanceof Error ? error.stack : String(error),
+                );
+              }
+            }
+            return outcome;
+          },
+        ),
+    });
+  }
+
+  private async tick(): Promise<void> {
+    if (this.ticking) {
+      return;
+    }
+    this.ticking = true;
+    try {
+      const result = await this.runOnce();
+      if (result.claimed > 0) {
+        this.logger.log(
+          `Outbox cycle: claimed ${result.claimed}, done ${result.done}, retried ${result.retried}, failed ${result.failed}.`,
+        );
+      }
+    } catch (error) {
+      this.logger.error('Outbox cycle failed.', error instanceof Error ? error.stack : error);
+    } finally {
+      this.ticking = false;
+    }
+  }
+}

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

@@ -0,0 +1,12 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsObject } from 'class-validator';
+
+export class CreateFormDefinitionDto {
+  @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/data-source-response.dto.ts

@@ -0,0 +1,19 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class DataSourceKeysResponseDto {
+  @ApiProperty({ type: [String], example: ['countries', 'departments'] })
+  items!: string[];
+}
+
+export class DataSourceOptionDto {
+  @ApiProperty({ oneOf: [{ type: 'string' }, { type: 'number' }], example: 'IN' })
+  value!: string | number;
+
+  @ApiPropertyOptional({ example: 'India' })
+  label?: string;
+}
+
+export class DataSourceOptionsResponseDto {
+  @ApiProperty({ type: [DataSourceOptionDto] })
+  items!: DataSourceOptionDto[];
+}

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

@@ -0,0 +1,33 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { IsIn, IsISO8601, IsOptional, IsString, MaxLength } from 'class-validator';
+
+export class ExportSubmissionsQueryDto {
+  @ApiPropertyOptional({ enum: ['csv', 'json'], default: 'json' })
+  @IsOptional()
+  @IsIn(['csv', 'json'])
+  format?: 'csv' | 'json';
+
+  @ApiPropertyOptional({ enum: ['DRAFT', 'SUBMITTED'] })
+  @IsOptional()
+  @IsIn(['DRAFT', 'SUBMITTED'])
+  status?: 'DRAFT' | 'SUBMITTED';
+
+  @ApiPropertyOptional({ format: 'date-time', description: 'Only submissions created at/after.' })
+  @IsOptional()
+  @IsISO8601()
+  from?: string;
+
+  @ApiPropertyOptional({ format: 'date-time', description: 'Only submissions created at/before.' })
+  @IsOptional()
+  @IsISO8601()
+  to?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Comma-separated field paths to include. Defaults to the definitions’ reportable fields. Sensitive fields are always refused.',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(2000)
+  fields?: string;
+}

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

@@ -0,0 +1,24 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class FileUploadResponseDto {
+  @ApiProperty({ example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3', format: 'uuid' })
+  fileId!: string;
+
+  @ApiProperty({ example: 'manuscript.pdf' })
+  originalName!: string;
+
+  @ApiProperty({ example: 'application/pdf', description: 'Server-sniffed MIME type.' })
+  mimeType!: string;
+
+  @ApiProperty({ example: 348160 })
+  size!: number;
+
+  @ApiProperty({ example: '9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08' })
+  checksum!: string;
+
+  @ApiProperty({ enum: ['TEMPORARY', 'SCANNING', 'CLEAN', 'INFECTED', 'LINKED'] })
+  status!: string;
+
+  @ApiProperty({ example: '2026-06-12T10:30:00.000Z', format: 'date-time' })
+  createdAt!: Date;
+}

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

@@ -0,0 +1,50 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class FormDefinitionResponseDto {
+  @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' })
+  key!: string;
+
+  @ApiProperty({ example: 1 })
+  version!: number;
+
+  @ApiProperty({ enum: ['DRAFT', 'PUBLISHED', 'ARCHIVED'], example: 'DRAFT' })
+  status!: 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
+
+  @ApiProperty({
+    type: 'object',
+    additionalProperties: true,
+    description: 'The full FormDefinition document.',
+  })
+  schema!: Record<string, unknown>;
+
+  @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 FormDefinitionListResponseDto {
+  @ApiProperty({ type: [FormDefinitionResponseDto] })
+  items!: FormDefinitionResponseDto[];
+
+  @ApiPropertyOptional({
+    type: String,
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+    nullable: true,
+  })
+  nextCursor!: string | null;
+}

package/template/src/modules/forms/dto/form-render-response.dto.ts

@@ -0,0 +1,17 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class FormRenderResponseDto {
+  @ApiProperty({
+    type: 'object',
+    additionalProperties: true,
+    description: 'The published FormDefinition document.',
+  })
+  definition!: Record<string, unknown>;
+
+  @ApiProperty({
+    type: 'object',
+    additionalProperties: true,
+    description: 'Resolved data-source options keyed by dotted field path.',
+  })
+  options!: Record<string, unknown>;
+}

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"]
+  }
+}