@ftisindia/create-app 0.1.5 → 0.1.6

package/template/src/modules/reports/dto/export-job-response.dto.ts

@@ -0,0 +1,60 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class ExportJobResponseDto {
+  @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 })
+  reportVersion!: number;
+
+  @ApiProperty({
+    type: 'object',
+    additionalProperties: true,
+    description: 'The FULL query spec, format, and resolved column list — replayable (finding #8).',
+  })
+  spec!: Record<string, unknown>;
+
+  @ApiProperty({
+    type: String,
+    format: 'date-time',
+    nullable: true,
+    description: 'Snapshot timestamp, set when the job runs (§9).',
+  })
+  asOf!: string | null;
+
+  @ApiProperty({ enum: ['PENDING', 'RUNNING', 'DONE', 'FAILED'], example: 'PENDING' })
+  status!: 'PENDING' | 'RUNNING' | 'DONE' | 'FAILED';
+
+  @ApiProperty({ type: String, format: 'uuid', nullable: true })
+  fileId!: string | null;
+
+  @ApiProperty({ type: Number, nullable: true, example: 52340 })
+  rowCount!: number | null;
+
+  @ApiProperty({ type: String, nullable: true })
+  error!: string | null;
+
+  @ApiProperty({
+    example: '4a4f0d8a-4bd2-469f-a6a9-3e1cb6a2b456',
+    format: 'uuid',
+  })
+  requestedBy!: string;
+
+  @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;
+}

package/template/src/modules/reports/dto/export-request.dto.ts

@@ -0,0 +1,34 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  IsArray,
+  IsIn,
+  IsObject,
+  IsOptional,
+  IsString,
+  ValidateNested,
+} from 'class-validator';
+import { QuerySpecDto } from './query-spec.dto';
+
+export class ExportRequestDto {
+  @ApiProperty({ enum: ['csv', 'xlsx'], example: 'csv' })
+  @IsIn(['csv', 'xlsx'])
+  format!: 'csv' | 'xlsx';
+
+  @ApiPropertyOptional({ type: QuerySpecDto })
+  @IsOptional()
+  @IsObject()
+  @ValidateNested()
+  @Type(() => QuerySpecDto)
+  spec?: QuerySpecDto;
+
+  @ApiPropertyOptional({
+    type: [String],
+    description:
+      'Explicit column-id projection. Columns marked exportable:false are stripped regardless (§9).',
+  })
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  columns?: string[];
+}

package/template/src/modules/reports/dto/list-reports-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 ListReportsQueryDto extends PaginationQueryDto {
+  @ApiPropertyOptional({ enum: ['DRAFT', 'PUBLISHED', 'ARCHIVED'] })
+  @IsOptional()
+  @IsIn(['DRAFT', 'PUBLISHED', 'ARCHIVED'])
+  status?: 'DRAFT' | 'PUBLISHED' | 'ARCHIVED';
+}

package/template/src/modules/reports/dto/list-views-query.dto.ts

@@ -0,0 +1,17 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, Min } from 'class-validator';
+
+export class ListViewsQueryDto {
+  @ApiPropertyOptional({
+    example: 3,
+    minimum: 1,
+    description:
+      'Version the compatibility verdicts are computed against; defaults to the latest published one (§4).',
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  version?: number;
+}

package/template/src/modules/reports/dto/prepare-action-response.dto.ts

@@ -0,0 +1,14 @@
+import { ApiProperty } from '@nestjs/swagger';
+
+export class PrepareActionResponseDto {
+  @ApiProperty({ example: 240, description: 'Rows the byFilter selection resolves to right now.' })
+  expectedCount!: number;
+
+  @ApiProperty({ example: '2026-06-01T10:30:00.000Z', format: 'date-time' })
+  asOf!: string;
+
+  @ApiProperty({
+    description: 'HMAC-signed, short-TTL token binding report, version, action, and spec (§6.3).',
+  })
+  actionToken!: string;
+}

package/template/src/modules/reports/dto/prepare-action.dto.ts

@@ -0,0 +1,27 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsDefined, IsObject, ValidateNested } from 'class-validator';
+import { QuerySpecDto } from './query-spec.dto';
+
+/**
+ * §6.3 step 1: only byFilter selections prepare — the server resolves the
+ * spec NOW and returns a signed token binding what was seen. byIds selections
+ * skip prepare entirely (the ids ARE the snapshot) and go straight to execute.
+ */
+export class PrepareActionSelectionDto {
+  @ApiProperty({ type: QuerySpecDto })
+  @IsDefined()
+  @IsObject()
+  @ValidateNested()
+  @Type(() => QuerySpecDto)
+  byFilter!: QuerySpecDto;
+}
+
+export class PrepareActionDto {
+  @ApiProperty({ type: PrepareActionSelectionDto })
+  @IsDefined()
+  @IsObject()
+  @ValidateNested()
+  @Type(() => PrepareActionSelectionDto)
+  selection!: PrepareActionSelectionDto;
+}

package/template/src/modules/reports/dto/query-response.dto.ts

@@ -0,0 +1,64 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class CountResultDto {
+  @ApiProperty({
+    enum: ['estimated', 'exact', 'capped'],
+    description: '"capped" means the true count exceeds the cap — render "value+" (§5.4).',
+  })
+  mode!: 'estimated' | 'exact' | 'capped';
+
+  @ApiProperty({ example: 1240 })
+  value!: number;
+}
+
+export class PageInfoDto {
+  @ApiProperty({
+    type: String,
+    nullable: true,
+    description: 'Opaque, HMAC-signed keyset cursor (§5.3). null on the last page.',
+  })
+  nextCursor!: string | null;
+
+  @ApiProperty({ example: true })
+  hasMore!: boolean;
+
+  @ApiPropertyOptional({ type: CountResultDto })
+  count?: CountResultDto;
+}
+
+export class QueryMetaDto {
+  @ApiProperty({ example: 4 })
+  reportVersion!: number;
+
+  @ApiProperty({ type: 'array', items: { type: 'object', additionalProperties: true } })
+  appliedFilters!: Record<string, unknown>[];
+
+  @ApiProperty({ type: 'array', items: { type: 'object', additionalProperties: true } })
+  appliedSort!: Record<string, unknown>[];
+
+  @ApiProperty({
+    type: String,
+    nullable: true,
+    format: 'date-time',
+    description: 'Materialized-tier staleness marker; null on live/indexed tiers (§8).',
+  })
+  freshAsOf!: string | null;
+
+  @ApiProperty({ example: 14 })
+  durationMs!: number;
+}
+
+export class QueryResponseDto {
+  @ApiProperty({
+    type: 'array',
+    items: { type: 'object', additionalProperties: true },
+    description: 'Rows: declared column ids plus $id (stable row identity) and $tags (§7).',
+  })
+  rows!: Record<string, unknown>[];
+
+  @ApiProperty({ type: PageInfoDto })
+  pageInfo!: PageInfoDto;
+
+  @ApiProperty({ type: QueryMetaDto })
+  meta!: QueryMetaDto;
+}

package/template/src/modules/reports/dto/query-spec.dto.ts

@@ -0,0 +1,120 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  IsArray,
+  IsDefined,
+  IsIn,
+  IsInt,
+  IsOptional,
+  IsString,
+  Min,
+  ValidateNested,
+} from 'class-validator';
+
+/**
+ * Envelope-only validation of the QuerySpec (report design §4/§10): the DTO
+ * checks the shape; the engine's compiler validates the semantics — column
+ * ids against the definition's allowlist, operators against column types,
+ * cursors against (key, version, sortHash, filterHash). A `contains` on a
+ * number column is the engine's 400, not this DTO's.
+ */
+export class FilterClauseDto {
+  @ApiProperty({
+    example: 'status',
+    description: 'A declared column id, or the virtual "$tags" column (§7).',
+  })
+  @IsString()
+  column!: string;
+
+  @ApiProperty({
+    example: 'eq',
+    description: 'Filter operator — validated against the column type by the engine.',
+  })
+  @IsString()
+  op!: string;
+
+  @ApiProperty({
+    description: 'Operand — any JSON value; the engine validates it against the column type.',
+  })
+  @IsDefined()
+  value!: unknown;
+}
+
+export class SortClauseDto {
+  @ApiProperty({ example: 'createdAt' })
+  @IsString()
+  column!: string;
+
+  @ApiProperty({ enum: ['asc', 'desc'], example: 'desc' })
+  @IsIn(['asc', 'desc'])
+  dir!: 'asc' | 'desc';
+}
+
+export class QuerySpecDto {
+  @ApiPropertyOptional({
+    type: Number,
+    nullable: true,
+    example: null,
+    description: 'null/omitted ⇒ latest published; or pin an explicit published version (§4).',
+  })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  version?: number | null;
+
+  @ApiPropertyOptional({ type: [FilterClauseDto] })
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => FilterClauseDto)
+  filters?: FilterClauseDto[];
+
+  @ApiPropertyOptional({
+    type: String,
+    nullable: true,
+    example: 'transformer',
+    description: "Free-text search across the definition's declared search columns (§5.5).",
+  })
+  @IsOptional()
+  @IsString()
+  search?: string | null;
+
+  @ApiPropertyOptional({ type: [SortClauseDto] })
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => SortClauseDto)
+  sort?: SortClauseDto[];
+
+  @ApiPropertyOptional({
+    type: String,
+    nullable: true,
+    description: 'Keyset cursor from the previous page, or null for page one (§5.3).',
+  })
+  @IsOptional()
+  @IsString()
+  cursor?: string | null;
+
+  @ApiPropertyOptional({ example: 50, minimum: 1, description: 'Capped server-side by policy.' })
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  pageSize?: number;
+
+  @ApiPropertyOptional({
+    enum: ['none', 'estimated', 'exact-capped'],
+    description: 'Counts are a choice, not a tax (§5.4).',
+  })
+  @IsOptional()
+  @IsIn(['none', 'estimated', 'exact-capped'])
+  count?: 'none' | 'estimated' | 'exact-capped';
+
+  @ApiPropertyOptional({
+    type: [String],
+    description: 'Projection: declared column ids to return. Default: all definition columns.',
+  })
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  columns?: string[];
+}

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

@@ -0,0 +1,64 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+
+export class ReportDefinitionResponseDto {
+  @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' })
+  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 ReportDefinition document.',
+  })
+  schema!: Record<string, unknown>;
+
+  @ApiPropertyOptional({
+    type: 'object',
+    additionalProperties: true,
+    nullable: true,
+    description:
+      'Publish-time compiled metadata (logical→physical column map, plan hashes); null on drafts.',
+  })
+  compiled!: Record<string, unknown> | 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 ReportDefinitionListResponseDto {
+  @ApiProperty({ type: [ReportDefinitionResponseDto] })
+  items!: ReportDefinitionResponseDto[];
+
+  @ApiPropertyOptional({
+    type: String,
+    example: '0a57fb4a-95c6-4f7e-bd5a-f96dbe0599e3',
+    format: 'uuid',
+    nullable: true,
+  })
+  nextCursor!: string | null;
+}
+
+export class ReportArchivedResponseDto {
+  @ApiProperty({ example: true })
+  archived!: boolean;
+}

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

@@ -0,0 +1,16 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, Min } from 'class-validator';
+
+export class ReportMetaQueryDto {
+  @ApiPropertyOptional({
+    example: 3,
+    minimum: 1,
+    description: 'Specific published version to describe; defaults to the latest published one.',
+  })
+  @IsOptional()
+  @Type(() => Number)
+  @IsInt()
+  @Min(1)
+  version?: number;
+}

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