@ftisindia/create-app 0.1.4 → 0.1.6

package/template/src/modules/reports/dto/report-meta-response.dto.ts

@@ -0,0 +1,113 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+/** Mirrors the engine's ReportMetaDescriptor (§4/§10) — the grid UI is generic. */
+export class ReportColumnMetaDto {
+  @ApiProperty({ example: 'status' })
+  id!: string;
+
+  @ApiProperty({ example: 'Status' })
+  header!: string;
+
+  @ApiProperty({ example: 'enum' })
+  type!: string;
+
+  @ApiProperty({ example: true })
+  sortable!: boolean;
+
+  @ApiProperty({ example: true })
+  filterable!: boolean;
+
+  @ApiProperty({ example: false })
+  searchable!: boolean;
+
+  @ApiProperty({
+    type: [String],
+    example: ['eq', 'in'],
+    description: 'The exact operator set this column accepts.',
+  })
+  operators!: string[];
+
+  @ApiPropertyOptional({ type: [String] })
+  enum?: string[];
+
+  @ApiPropertyOptional({ type: 'object', additionalProperties: true })
+  lookup?: Record<string, unknown>;
+
+  @ApiProperty({ example: true })
+  exportable!: boolean;
+
+  @ApiPropertyOptional({
+    type: 'object',
+    additionalProperties: true,
+    description: 'Opaque UI hints — never interpreted by the backend.',
+  })
+  ui?: Record<string, unknown>;
+}
+
+export class ReportRowActionMetaDto {
+  @ApiProperty({ example: 'markReviewed' })
+  name!: string;
+
+  @ApiProperty({ enum: ['transactional', 'post-commit'], example: 'transactional' })
+  kind!: string;
+
+  @ApiPropertyOptional({
+    type: 'object',
+    additionalProperties: true,
+    description: 'JSON Schema for the action input, when the action declares one.',
+  })
+  inputSchema?: Record<string, unknown>;
+
+  @ApiProperty({ example: false })
+  destructive!: boolean;
+}
+
+export class ReportExportMetaDto {
+  @ApiProperty({ type: [String], example: ['csv', 'xlsx'] })
+  formats!: string[];
+
+  @ApiProperty({ example: 10000 })
+  maxRowsSync!: number;
+}
+
+export class ReportMetaResponseDto {
+  @ApiProperty({ example: 'abstract-review-board' })
+  reportKey!: string;
+
+  @ApiProperty({ example: 4 })
+  reportVersion!: number;
+
+  @ApiPropertyOptional({ example: 'Abstract review board' })
+  title?: string;
+
+  @ApiPropertyOptional({ example: 'All submitted abstracts with review status.' })
+  description?: string;
+
+  @ApiProperty({ type: [ReportColumnMetaDto] })
+  columns!: ReportColumnMetaDto[];
+
+  @ApiProperty({
+    type: 'array',
+    items: { type: 'object', additionalProperties: true },
+    example: [{ column: 'createdAt', dir: 'desc' }],
+  })
+  defaultSort!: Record<string, unknown>[];
+
+  @ApiProperty({ example: true })
+  searchEnabled!: boolean;
+
+  @ApiProperty({ type: [ReportRowActionMetaDto] })
+  rowActions!: ReportRowActionMetaDto[];
+
+  @ApiProperty({ type: ReportExportMetaDto })
+  export!: ReportExportMetaDto;
+
+  @ApiProperty({ example: 'indexed' })
+  performanceTier!: string;
+
+  @ApiPropertyOptional({
+    example: 900,
+    description: 'Declared staleness bound for materialized-tier reports, in seconds (§8).',
+  })
+  stalenessSeconds?: number;
+}

package/template/src/modules/reports/dto/saved-view-response.dto.ts

@@ -0,0 +1,66 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class ViewCompatibilityDto {
+  @ApiProperty({
+    enum: ['ok', 'degraded', 'incompatible'],
+    description: 'Verdict against the requested report version (§4, finding #1).',
+  })
+  status!: 'ok' | 'degraded' | 'incompatible';
+
+  @ApiProperty({ type: [String] })
+  missingColumns!: string[];
+
+  @ApiProperty({ type: [String] })
+  retypedColumns!: string[];
+}
+
+export class SavedViewResponseDto {
+  @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-review-board' })
+  reportKey!: string;
+
+  @ApiProperty({
+    example: 4,
+    description: 'The version the view was authored against (finding #1).',
+  })
+  reportVersion!: number;
+
+  @ApiProperty({ example: 'My ML shortlist' })
+  name!: string;
+
+  @ApiProperty({ type: 'object', additionalProperties: true })
+  spec!: Record<string, unknown>;
+
+  @ApiProperty({
+    type: String,
+    format: 'uuid',
+    nullable: true,
+    description: 'null ⇒ shared with the org (creation gated by reports.update, §10).',
+  })
+  ownerId!: string | null;
+
+  @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
+  createdAt!: string;
+
+  @ApiPropertyOptional({
+    type: ViewCompatibilityDto,
+    description: 'Present on list responses only.',
+  })
+  compatibility?: ViewCompatibilityDto;
+}
+
+export class SavedViewListResponseDto {
+  @ApiProperty({ type: [SavedViewResponseDto] })
+  items!: SavedViewResponseDto[];
+}

package/template/src/modules/reports/dto/update-report-definition.dto.ts

@@ -0,0 +1,9 @@
+import { CreateReportDefinitionDto } from './create-report-definition.dto';
+
+/**
+ * Same envelope as create — the body IS the full ReportDefinition document.
+ * The engine enforces the rest: the document key must match the route's
+ * report, drafts mutate in place, and editing a published version opens a new
+ * draft (report design §2/§10).
+ */
+export class UpdateReportDefinitionDto extends CreateReportDefinitionDto {}

package/template/src/modules/reports/dto/update-saved-view.dto.ts

@@ -0,0 +1,27 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  IsObject,
+  IsOptional,
+  IsString,
+  MaxLength,
+  MinLength,
+  ValidateNested,
+} from 'class-validator';
+import { QuerySpecDto } from './query-spec.dto';
+
+export class UpdateSavedViewDto {
+  @ApiPropertyOptional({ example: 'My ML shortlist', minLength: 1, maxLength: 120 })
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(120)
+  name?: string;
+
+  @ApiPropertyOptional({ type: QuerySpecDto })
+  @IsOptional()
+  @IsObject()
+  @ValidateNested()
+  @Type(() => QuerySpecDto)
+  spec?: QuerySpecDto;
+}

package/template/src/modules/reports/examples/abstract-review-board.report.json

@@ -0,0 +1,54 @@
+{
+  "key": "abstract-review-board",
+  "version": 1,
+  "status": "PUBLISHED",
+  "title": "Abstract submissions — review board",
+  "description": "Review grid over the abstract-submission form. Column ids follow the form-adapter convention (field path with dots replaced by underscores); $row.* references the physical FormSubmission columns the adapter allowlists. Only indexHint fields are sortable; the indexed tier's publish lint demands their generated columns and indexes.",
+  "source": { "kind": "form", "key": "abstract-submission" },
+  "columns": [
+    {
+      "id": "title",
+      "header": "Title",
+      "path": "title",
+      "type": "text",
+      "filterable": true
+    },
+    {
+      "id": "track",
+      "header": "Track",
+      "path": "track",
+      "type": "lookup",
+      "sortable": true,
+      "filterable": true,
+      "lookup": { "dataSource": "conference-tracks" }
+    },
+    {
+      "id": "status",
+      "header": "Status",
+      "path": "$row.status",
+      "type": "enum",
+      "sortable": true,
+      "filterable": true,
+      "enum": ["DRAFT", "SUBMITTED"]
+    },
+    {
+      "id": "createdAt",
+      "header": "Submitted",
+      "path": "$row.createdAt",
+      "type": "datetime",
+      "sortable": true,
+      "filterable": true
+    },
+    {
+      "id": "createdBy",
+      "header": "Submitted by",
+      "path": "$row.createdBy",
+      "type": "text",
+      "filterable": true
+    }
+  ],
+  "defaultSort": [{ "column": "createdAt", "dir": "desc" }],
+  "rowActions": ["updateStatus", "editSubmission", "manageTags"],
+  "export": { "formats": ["csv", "xlsx"] },
+  "performanceTier": "indexed"
+}

package/template/src/modules/reports/examples/org-members.report.json

@@ -0,0 +1,55 @@
+{
+  "key": "org-members",
+  "version": 1,
+  "status": "PUBLISHED",
+  "title": "Organisation members",
+  "description": "Every membership in the active organisation with user, role, and status — the Phase-1 standalone example: a custom source with no form-builder involvement.",
+  "source": { "kind": "custom", "key": "org-members" },
+  "columns": [
+    {
+      "id": "displayName",
+      "header": "Name",
+      "columnId": "displayName",
+      "type": "text",
+      "sortable": true,
+      "filterable": true,
+      "searchable": true
+    },
+    {
+      "id": "email",
+      "header": "Email",
+      "columnId": "email",
+      "type": "text",
+      "sortable": true,
+      "filterable": true
+    },
+    {
+      "id": "role",
+      "header": "Role",
+      "columnId": "role",
+      "type": "text",
+      "sortable": true,
+      "filterable": true
+    },
+    {
+      "id": "status",
+      "header": "Status",
+      "columnId": "status",
+      "type": "enum",
+      "filterable": true,
+      "enum": ["ACTIVE", "SUSPENDED", "REVOKED"]
+    },
+    {
+      "id": "joinedAt",
+      "header": "Joined",
+      "columnId": "joinedAt",
+      "type": "datetime",
+      "sortable": true
+    }
+  ],
+  "defaultSort": [{ "column": "joinedAt", "dir": "desc" }],
+  "search": { "columns": ["displayName"] },
+  "rowActions": ["manageTags"],
+  "export": { "formats": ["csv", "xlsx"] },
+  "performanceTier": "live"
+}

package/template/src/modules/reports/infrastructure/audit-sink.adapter.ts

@@ -0,0 +1,31 @@
+import { Injectable } from '@nestjs/common';
+import { Prisma } from '@prisma/client';
+import type { AuditEntry, EngineTx, ReportsAuditSink } from '@ftisindia/report-builder';
+import { PrismaService } from '../../../database/prisma/prisma.service';
+import { AuditService } from '../../audit/application/services/audit.service';
+
+/**
+ * Routes engine audit entries through the template's AuditService. When the
+ * engine supplies a transaction, the audit row is written through it so it
+ * commits atomically with the change it describes (ecosystem guide §7) —
+ * exports and bulk actions are audited as the PII egress they are (§9).
+ */
+@Injectable()
+export class PrismaReportsAuditSink implements ReportsAuditSink {
+  constructor(
+    private readonly audit: AuditService,
+    private readonly prisma: PrismaService,
+  ) {}
+
+  async write(entry: AuditEntry, tx?: EngineTx): Promise<void> {
+    const client = tx ? (tx as unknown as Prisma.TransactionClient) : this.prisma;
+    await this.audit.write(client, {
+      orgId: entry.orgId ?? null,
+      actorUserId: entry.actorUserId ?? null,
+      action: entry.action,
+      targetType: entry.targetType,
+      targetId: entry.targetId ?? null,
+      metadata: entry.metadata as Prisma.InputJsonValue | undefined,
+    });
+  }
+}

package/template/src/modules/reports/infrastructure/casl-reports-authorization.ts

@@ -0,0 +1,39 @@
+import { Injectable } from '@nestjs/common';
+import type { ReportsAuthorization, ReportsContext } from '@ftisindia/report-builder';
+import { AbilityFactory } from '../../access-control/application/services/ability.factory';
+import { permissionKeyToRule } from '../../access-control/types/permission-key';
+import { RequestContextService } from '../../request-context/application/services/request-context.service';
+
+/**
+ * The engine's internal authorization seam over CASL — mirrors
+ * PermissionGuard's own logic and fails closed when no RBAC context exists
+ * (anonymous/public requests). Route guards remain the first enforcement
+ * layer; this is the defense-in-depth second layer (ecosystem guide §5.3).
+ *
+ * Required keys are plain two-segment strings by design: row actions declare
+ * keys from ANY domain (e.g. 'formSubmissions.update'), not just 'reports.*'
+ * (report design §6.1) — permissionKeyToRule splits them generically.
+ */
+@Injectable()
+export class CaslReportsAuthorization implements ReportsAuthorization {
+  constructor(
+    private readonly abilities: AbilityFactory,
+    private readonly ctx: RequestContextService,
+  ) {}
+
+  can(required: readonly string[], ctx: ReportsContext): boolean {
+    // Fail closed: no authenticated user inside an active org ⇒ no capability.
+    if (!ctx.userId() || !ctx.orgId()) {
+      return false;
+    }
+    const rbac = this.ctx.getRbacContext();
+    if (!rbac) {
+      return false;
+    }
+    const ability = this.abilities.createForContext(rbac);
+    return required.every((key) => {
+      const { action, subject } = permissionKeyToRule(key);
+      return ability.can(action, subject);
+    });
+  }
+}

package/template/src/modules/reports/infrastructure/forms-adapter/form-report-source.adapter.ts

@@ -0,0 +1,292 @@
+import { Injectable } from '@nestjs/common';
+import {
+  generatedColumnComment,
+  generatedColumnExpression,
+  generatedColumnIndexes,
+  generatedColumnName,
+} from '@ftisindia/report-builder';
+import type {
+  ColumnType,
+  GeneratedIndexPlan,
+  IndexSpec,
+  ManifestColumn,
+  ReportsContext,
+  ResolvedSource,
+  SourceBinding,
+  SourceManifest,
+  SourceProvider,
+  SourceQuery,
+} from '@ftisindia/report-builder';
+import { walkFields } from '@ftisindia/form-builder';
+import type { FieldDef, FormDefinition } from '@ftisindia/form-builder';
+import { PrismaFormDefinitionStore } from '../../../forms/infrastructure/stores';
+
+/**
+ * `kind: "form"` source provider (report design §3.1) — the quick path. Maps a
+ * published FormDefinition onto the same SourceManifest interface every custom
+ * source implements, so the compiler never knows forms exist.
+ *
+ * THE STANDALONE GUARANTEE, INVERTED (§3.2): the report-builder core contains
+ * zero knowledge of the form builder, and this file is the ONLY place the two
+ * engines meet. Remove this provider (and the row actions beside it) and the
+ * report module still ships full reporting over custom sources.
+ *
+ * COLUMN-ID CONVENTION: each reportable field becomes one manifest column
+ * whose id is the field's dot path with dots replaced by '_' (e.g.
+ * `contact.email` → `contact_email`). Definitions over form sources reference
+ * fields via plain-path columns, and plain-path allowlist resolution maps by
+ * the DEFINITION column's own id — so a definition column over a form source
+ * MUST use this id convention (`{ "id": "contact_email", "path":
+ * "contact.email" }`) or it will not resolve against the manifest.
+ *
+ * VERSION NOTE (§3.1): the design's renamed-field `CASE ON "formVersion"` map
+ * requires rename metadata that FieldDef does not carry today, so this adapter
+ * resolves against the LATEST PUBLISHED definition version only. Submissions
+ * stamp `formVersion`, which is exactly what a future version-aware upgrade
+ * needs — nothing here forecloses it.
+ */
+@Injectable()
+export class FormReportSourceProvider implements SourceProvider {
+  readonly kind = 'form';
+
+  constructor(private readonly definitions: PrismaFormDefinitionStore) {}
+
+  /**
+   * Resolve a `{ kind: 'form', key: <formKey> }` binding to the manifest +
+   * base query the compiler consumes. Null (→ ReportNotFoundError upstream)
+   * when no org scope is active or the form has no published version.
+   */
+  async resolve(binding: SourceBinding, ctx: ReportsContext): Promise<ResolvedSource | null> {
+    const orgId = ctx.orgId();
+    if (orgId === undefined) {
+      return null;
+    }
+    const record = await this.definitions.findLatest(orgId, binding.key, 'PUBLISHED');
+    if (record === null) {
+      return null;
+    }
+
+    const manifest: SourceManifest = {
+      // The submission row id — what tags, row actions, and the keyset
+      // tiebreaker bind to (§7).
+      rowId: '"id"',
+      orgScoped: true,
+      columns: [...this.autoColumns(binding.key, record.schema), ...physicalRowColumns()],
+    };
+
+    const baseQuery: SourceQuery = {
+      from: '"FormSubmission"',
+      orgColumn: '"orgId"',
+      primaryTable: 'FormSubmission',
+      // Code-owned discriminator — multiple forms share one physical table.
+      where: [{ sql: '"formKey" = ?', params: [binding.key] }],
+    };
+
+    return { kind: this.kind, key: binding.key, manifest, baseQuery };
+  }
+
+  /**
+   * Auto-columns from form fields (§3.1): every `reportable: true` field with
+   * a mappable type becomes a manifest column over the JSONB extraction
+   * expression (the live tier reads it directly; the indexed tier's generated
+   * column uses the SAME expression, §8.1).
+   *
+   * Skipped on purpose:
+   * - `sensitive` fields — their values never reach action logs, audit
+   *   metadata, or exports (form engine contract), so they never enter a
+   *   report manifest either;
+   * - file/password fields (and any type outside the map) — files are
+   *   references, passwords are always-sensitive; neither is tabular data;
+   * - repeatable groups and every field inside one — a repeatable group is an
+   *   array of objects, so one submission row maps to MANY values: a scalar
+   *   JSONB extraction would return NULL or require flattening the row set,
+   *   which is a materialization concern (§8), not a column.
+   */
+  private autoColumns(formKey: string, definition: FormDefinition): ManifestColumn[] {
+    const columns: ManifestColumn[] = [];
+    const reserved = new Set(physicalRowColumns().map((column) => column.id));
+    const repeatableRoots: string[] = [];
+
+    walkFields(definition.fields, (field, segments) => {
+      const path = segments.join('.');
+      // walkFields is depth-first pre-order: a repeatable ancestor is always
+      // recorded before its children are visited.
+      if (repeatableRoots.some((root) => path === root || path.startsWith(`${root}.`))) {
+        return;
+      }
+      if (field.repeatable === true) {
+        repeatableRoots.push(path);
+        return;
+      }
+      if (field.reportable !== true || field.sensitive === true) {
+        return;
+      }
+      const type = mapFieldType(field);
+      if (type === undefined) {
+        return;
+      }
+      const id = path.replace(/\./g, '_');
+      if (reserved.has(id)) {
+        // A field named like a physical $row column would make the allowlist
+        // ambiguous (§5.1) — the physical column wins; rename the field.
+        return;
+      }
+      columns.push(this.buildColumn(formKey, path, id, type, field));
+    });
+
+    return columns;
+  }
+
+  private buildColumn(
+    formKey: string,
+    path: string,
+    id: string,
+    type: ColumnType,
+    field: FieldDef,
+  ): ManifestColumn {
+    const extraction = generatedColumnExpression(path, type);
+    const hot = field.indexHint === true;
+    const searchable = hot && type === 'text';
+    // SORTABILITY needs non-null keys (§5.3): indexHint fields get the
+    // COALESCE-wrapped expression — in BOTH the queryable sql and the
+    // generated column, so the index is built on exactly what is compared —
+    // and are declared non-nullable. Fields without the hint stay un-wrapped,
+    // filterable-only, nullable.
+    const expression = hot ? `COALESCE(${extraction}, ${nullFallback(type)})` : extraction;
+    const name = generatedColumnName(formKey, path, type);
+    const plans = generatedColumnIndexes(name, type, { table: 'FormSubmission', searchable });
+    const index = plans.length > 0 ? toIndexSpec(plans[0]) : undefined;
+    const trgmPlan = plans.find((plan) => plan.using === 'gin');
+    const searchIndex = searchable && trgmPlan ? toIndexSpec(trgmPlan) : undefined;
+
+    return {
+      id,
+      sql: expression,
+      type,
+      sortable: hot,
+      filterable: true,
+      ...(searchable ? { searchable: true, search: { mode: 'trgm' as const } } : {}),
+      nullable: !hot,
+      // The §8.1 storage trick: dates are canonical ISO-8601 UTC TEXT, so the
+      // lookup binding for `select` fields lives in the DEFINITION column
+      // (lookup.dataSource); the manifest only types it 'lookup'.
+      ...(type === 'datetime' ? { valueKind: 'isoText' as const } : {}),
+      // The physical column the indexed tier publishes against (§8.1); the
+      // publish lint verifies it exists and suggests the exact ALTER TABLE.
+      generated: {
+        table: 'FormSubmission',
+        name,
+        expression,
+        comment: generatedColumnComment(formKey, path, type),
+        sqlType: generatedSqlType(type),
+      },
+      ...(index ? { index } : {}),
+      ...(searchIndex ? { searchIndex } : {}),
+    };
+  }
+}
+
+/** §3.1 field-type map — anything outside it is skipped, by design. */
+function mapFieldType(field: FieldDef): ColumnType | undefined {
+  switch (field.type) {
+    case 'text':
+    case 'email':
+      return 'text';
+    case 'number':
+      return 'number';
+    case 'boolean':
+      return 'boolean';
+    case 'select':
+      return 'lookup';
+    case 'date':
+      return 'datetime';
+    default:
+      return undefined;
+  }
+}
+
+/** Typed COALESCE fallback for indexHint columns (§5.3 non-null sort keys). */
+function nullFallback(type: ColumnType): string {
+  switch (type) {
+    case 'number':
+      return '0';
+    case 'boolean':
+      return 'false';
+    default:
+      // text/enum/lookup — and datetime, which is ISO-8601 UTC TEXT (§8.1).
+      return "''";
+  }
+}
+
+/** Stored SQL type of the generated column (the §8.1 casting table). */
+function generatedSqlType(type: ColumnType): string {
+  switch (type) {
+    case 'number':
+      return 'numeric';
+    case 'boolean':
+      return 'boolean';
+    default:
+      return 'text';
+  }
+}
+
+function toIndexSpec(plan: GeneratedIndexPlan): IndexSpec {
+  return { name: plan.name, kind: plan.using, table: 'FormSubmission', expr: plan.expr };
+}
+
+/**
+ * The §2.1 allowlist of PHYSICAL FormSubmission columns, referenced as
+ * `$row.<id>` in definitions. Index specs name the indexes the template's
+ * Prisma schema already creates — declared capabilities stay honest (§5.2).
+ */
+function physicalRowColumns(): ManifestColumn[] {
+  return [
+    {
+      id: 'status',
+      sql: '"status"::text',
+      type: 'enum',
+      filterable: true,
+      sortable: true,
+      nullable: false,
+      index: {
+        name: 'FormSubmission_orgId_formKey_status_idx',
+        kind: 'btree',
+        table: 'FormSubmission',
+        expr: '"orgId", "formKey", "status"',
+      },
+    },
+    {
+      id: 'createdAt',
+      sql: '"createdAt"',
+      type: 'datetime',
+      valueKind: 'native',
+      sortable: true,
+      filterable: true,
+      nullable: false,
+      index: {
+        name: 'FormSubmission_orgId_createdAt_idx',
+        kind: 'btree',
+        table: 'FormSubmission',
+        expr: '"orgId", "createdAt"',
+      },
+    },
+    {
+      id: 'updatedAt',
+      sql: '"updatedAt"',
+      type: 'datetime',
+      valueKind: 'native',
+      sortable: true,
+      nullable: false,
+      // No index declared: sortable on the live tier only until an app
+      // publishes an indexed report over it.
+    },
+    {
+      id: 'createdBy',
+      sql: '"createdBy"',
+      type: 'text',
+      filterable: true,
+      // Null for anonymous/public submissions — filterable only.
+      nullable: true,
+    },
+  ];
+}