@ftisindia/create-app 0.1.4 → 0.1.6

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

@@ -0,0 +1,86 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  Allow,
+  ArrayMinSize,
+  IsArray,
+  IsIn,
+  IsObject,
+  IsOptional,
+  IsString,
+  Matches,
+} from 'class-validator';
+
+/**
+ * The request body IS the ReportDefinition document (report design §2/§10).
+ * Envelope-only validation — the same two-layer split as forms: this DTO
+ * whitelists the document's top-level keys (the global ValidationPipe runs
+ * with forbidNonWhitelisted) and checks the cheap invariants; the engine's
+ * meta-schema + linter are the real gate for everything nested (columns,
+ * source binding, export config, ...), so nested content passes through
+ * untouched.
+ */
+export class CreateReportDefinitionDto {
+  @ApiProperty({ example: 'abstract-review-board' })
+  @IsString()
+  @Matches(/^[a-z][a-z0-9-]*$/)
+  key!: string;
+
+  @ApiPropertyOptional({ example: 'Abstract review board' })
+  @IsOptional()
+  @IsString()
+  title?: string;
+
+  @ApiPropertyOptional({ example: 'All submitted abstracts with review status.' })
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @ApiProperty({
+    type: 'object',
+    additionalProperties: true,
+    description: 'Source binding ({ kind, key, options? }) — resolved and validated by the engine.',
+  })
+  @IsObject()
+  source!: Record<string, unknown>;
+
+  @ApiProperty({
+    type: 'array',
+    items: { type: 'object', additionalProperties: true },
+    description: 'Column definitions — validated against the engine meta-schema and linter.',
+  })
+  @IsArray()
+  @ArrayMinSize(1)
+  columns!: Record<string, unknown>[];
+
+  @ApiPropertyOptional({
+    type: 'array',
+    items: { type: 'object', additionalProperties: true },
+  })
+  @Allow()
+  defaultSort?: unknown;
+
+  @ApiPropertyOptional({ type: 'object', additionalProperties: true })
+  @Allow()
+  search?: unknown;
+
+  @ApiPropertyOptional({ type: [String] })
+  @Allow()
+  rowActions?: unknown;
+
+  @ApiPropertyOptional({ type: 'object', additionalProperties: true })
+  @Allow()
+  export?: unknown;
+
+  @ApiProperty({ enum: ['live', 'indexed', 'materialized'], example: 'indexed' })
+  @IsIn(['live', 'indexed', 'materialized'])
+  performanceTier!: 'live' | 'indexed' | 'materialized';
+
+  // Server-assigned; tolerated on input so fetched documents round-trip.
+  @ApiPropertyOptional({ description: 'Server-assigned; ignored on input.' })
+  @Allow()
+  version?: unknown;
+
+  @ApiPropertyOptional({ description: 'Server-assigned; ignored on input.' })
+  @Allow()
+  status?: unknown;
+}

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

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

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

@@ -0,0 +1,71 @@
+import { ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  ArrayMaxSize,
+  IsArray,
+  IsObject,
+  IsOptional,
+  IsString,
+  MaxLength,
+  MinLength,
+  ValidateNested,
+} from 'class-validator';
+import { QuerySpecDto } from './query-spec.dto';
+
+/**
+ * Bulk selection (§6.3): exactly one of byIds / byFilter — enforced by the
+ * engine. byIds is self-snapshotting and capped; byFilter requires the
+ * prepared action token because rows matching at confirmation may differ at
+ * execution.
+ */
+export class ExecuteActionSelectionDto {
+  @ApiPropertyOptional({ type: [String], maxItems: 1000 })
+  @IsOptional()
+  @IsArray()
+  @ArrayMaxSize(1000)
+  @IsString({ each: true })
+  byIds?: string[];
+
+  @ApiPropertyOptional({ type: QuerySpecDto })
+  @IsOptional()
+  @IsObject()
+  @ValidateNested()
+  @Type(() => QuerySpecDto)
+  byFilter?: QuerySpecDto;
+}
+
+export class ExecuteActionDto {
+  @ApiPropertyOptional({ type: ExecuteActionSelectionDto })
+  @IsOptional()
+  @IsObject()
+  @ValidateNested()
+  @Type(() => ExecuteActionSelectionDto)
+  selection?: ExecuteActionSelectionDto;
+
+  @ApiPropertyOptional({
+    description: 'Prepared action token — REQUIRED for byFilter selections (§6.3).',
+  })
+  @IsOptional()
+  @IsString()
+  actionToken?: string;
+
+  @ApiPropertyOptional({
+    type: 'object',
+    additionalProperties: true,
+    description: "Action input — validated against the action's JSON Schema by the engine.",
+  })
+  @IsOptional()
+  @IsObject()
+  input?: Record<string, unknown>;
+
+  @ApiPropertyOptional({
+    minLength: 1,
+    maxLength: 120,
+    description: 'Idempotency ledger key — retries return the recorded outcome (§6.3).',
+  })
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(120)
+  idempotencyKey?: string;
+}

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