@fiado/type-kit 3.574.0 → 3.576.0

package/src/rules/constants/RulesLimits.ts

@@ -6,3 +6,9 @@ export const RULES_INPUT_SOURCE = 'input';
 export const RULES_MAX_INPUT_CONTRACT = 30;
 /** Largo máximo (caracteres) del contenido de un turno del chat de `POST /generate`. */
 export const RULES_CHAT_TURN_MAX_LENGTH = 4000;
+/** Máximo de sujetos por query asíncrona de evaluación DATALAKE (`POST /evaluate/executions`). */
+export const RULES_MAX_SUBJECTS_PER_DATALAKE_CALL = 1000;
+/** Máximo de `returnFields` por llamada. */
+export const RULES_MAX_RETURN_FIELDS = 20;
+/** Id de campo devuelto: `fuente:campo` (campo del catálogo) o `tabla.ruta.hoja` (hoja del esquema aplanado de Glue). */
+export const RETURN_FIELD_ID_PATTERN = /^(?:[a-z][a-z0-9-]*:[A-Za-z][A-Za-z0-9_]*|[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*){1,8})$/;

package/src/rules/dtos/EvaluateRulesRequest.ts

@@ -1,7 +1,10 @@
 import { Expose, Type } from 'class-transformer';
-import { IsArray, IsISO8601, IsObject, IsOptional, IsString, ValidateNested } from 'class-validator';
+import { ArrayMaxSize, IsArray, IsEnum, IsISO8601, IsObject, IsOptional, IsString, Matches, ValidateNested } from 'class-validator';
 import { JsonValue } from '../../common';
+import { InputField } from '../../dynamicForm/dtos/InputField';
 import { DynamicFormValue } from '../../dynamicForm/types/DynamicFormValue';
+import { RETURN_FIELD_ID_PATTERN, RULES_MAX_INPUT_CONTRACT, RULES_MAX_RETURN_FIELDS } from '../constants/RulesLimits';
+import { EvaluationStrategyEnum } from '../enums/EvaluationStrategyEnum';
 
 /** A quién se le evalúa la regla. */
 export class RulesEvaluationSubject {
@@ -64,4 +67,26 @@ export class EvaluateRulesRequest {
     @IsOptional()
     @IsISO8601()
     referenceAt?: string;
+
+    /** Estrategia de evaluación; ausente = `LIVE`. */
+    @Expose()
+    @IsOptional()
+    @IsEnum(EvaluationStrategyEnum)
+    evaluationStrategy?: EvaluationStrategyEnum;
+
+    /** Campos a devolver por sujeto (`fuente:campo` o `tabla.ruta.hoja`); máx. 20. Se leen del datalake. */
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayMaxSize(RULES_MAX_RETURN_FIELDS)
+    @Matches(RETURN_FIELD_ID_PATTERN, { each: true })
+    returnFields?: string[];
+
+    /** Contrato de la fuente `input` (tipos de las columnas `i_<llave>` en DATALAKE). */
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayMaxSize(RULES_MAX_INPUT_CONTRACT)
+    @IsObject({ each: true })
+    inputContract?: InputField[];
 }

package/src/rules/dtos/EvaluateRulesResponse.ts

@@ -1,3 +1,4 @@
+import { JsonValue } from '../../common';
 import { RulesOutcomeEnum } from '../enums/RulesOutcomeEnum';
 import { RulesTraceResponse } from './RulesTraceResponse';
 
@@ -11,6 +12,8 @@ export class RuleEvaluationResult {
     trace?: RulesTraceResponse;
     /** Solo si `outcome` es `ERROR`. */
     errorMessage?: string;
+    /** Campos devueltos pedidos en `returnFields`: clave = id del campo; `null` = sin dato. */
+    returned?: Record<string, JsonValue>;
 }
 
 /** `POST /evaluate`: ordenado por regla y, dentro de cada regla, por `subjectIndex`. */

package/src/rules/dtos/ValidateRulesRequest.ts

@@ -1,8 +1,9 @@
 import { Expose } from 'class-transformer';
-import { ArrayMaxSize, IsArray, IsObject, IsOptional, IsString } from 'class-validator';
+import { ArrayMaxSize, IsArray, IsEnum, IsObject, IsOptional, IsString, Matches } from 'class-validator';
 import { JsonValue } from '../../common';
 import { InputField } from '../../dynamicForm/dtos/InputField';
-import { RULES_MAX_INPUT_CONTRACT } from '../constants/RulesLimits';
+import { RETURN_FIELD_ID_PATTERN, RULES_MAX_INPUT_CONTRACT, RULES_MAX_RETURN_FIELDS } from '../constants/RulesLimits';
+import { EvaluationStrategyEnum } from '../enums/EvaluationStrategyEnum';
 
 /** `POST /validate`: valida una regla guardada contra el catálogo de los ítems indicados y el contrato de `input`. */
 export class ValidateRulesRequest {
@@ -30,4 +31,18 @@ export class ValidateRulesRequest {
     @ArrayMaxSize(RULES_MAX_INPUT_CONTRACT)
     @IsObject({ each: true })
     inputContract?: InputField[];
+
+    /** Estrategia contra la que se valida; ausente = `LIVE`. */
+    @Expose()
+    @IsOptional()
+    @IsEnum(EvaluationStrategyEnum)
+    evaluationStrategy?: EvaluationStrategyEnum;
+
+    /** Campos devueltos a validar (`fuente:campo` o `tabla.ruta.hoja`); máx. 20. */
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayMaxSize(RULES_MAX_RETURN_FIELDS)
+    @Matches(RETURN_FIELD_ID_PATTERN, { each: true })
+    returnFields?: string[];
 }

package/src/rules/dtos/datalake/EvaluationExecutionRequest.ts

@@ -0,0 +1,73 @@
+import { Expose, Type } from 'class-transformer';
+import { ArrayMaxSize, ArrayMinSize, IsArray, IsISO8601, IsObject, IsOptional, IsString, Matches, MaxLength, MinLength, ValidateNested } from 'class-validator';
+import { InputField } from '../../../dynamicForm/dtos/InputField';
+import {
+    RETURN_FIELD_ID_PATTERN,
+    RULES_MAX_INPUT_CONTRACT,
+    RULES_MAX_RETURN_FIELDS,
+    RULES_MAX_SUBJECTS_PER_DATALAKE_CALL,
+} from '../../constants/RulesLimits';
+import { RuleToEvaluate, RulesEvaluationSubject } from '../EvaluateRulesRequest';
+
+/**
+ * `POST /evaluate/executions`: inicia UNA query Athena por lote (hasta 1000 sujetos).
+ * `rules` ausente = modo "solo campos" (exige `returnFields` ≥ 1: esa regla la valida el lambda).
+ */
+export class EvaluationExecutionRequest {
+    /** Quién llama (solo logs y métricas). */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    consumer?: string;
+
+    /** Ids de ítems del catálogo (`source:key`) que las reglas pueden usar. */
+    @Expose()
+    @IsArray()
+    @IsString({ each: true })
+    items: string[];
+
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayMinSize(1)
+    @ArrayMaxSize(10)
+    @ValidateNested({ each: true })
+    @Type(() => RuleToEvaluate)
+    rules?: RuleToEvaluate[];
+
+    /** Contrato de la fuente `input` (tipos de las columnas `i_<llave>`). */
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayMaxSize(RULES_MAX_INPUT_CONTRACT)
+    @IsObject({ each: true })
+    inputContract?: InputField[];
+
+    @Expose()
+    @IsArray()
+    @ArrayMinSize(1)
+    @ArrayMaxSize(RULES_MAX_SUBJECTS_PER_DATALAKE_CALL)
+    @ValidateNested({ each: true })
+    @Type(() => RulesEvaluationSubject)
+    subjects: RulesEvaluationSubject[];
+
+    /** Fecha ISO 8601 con hora (ancla del cálculo, nunca `now()`). */
+    @Expose()
+    @IsISO8601({ strict: true })
+    @Matches(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/)
+    referenceAt: string;
+
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayMaxSize(RULES_MAX_RETURN_FIELDS)
+    @Matches(RETURN_FIELD_ID_PATTERN, { each: true })
+    returnFields?: string[];
+
+    /** Mismo lote reintentado = mismo `QueryExecutionId`. */
+    @Expose()
+    @IsString()
+    @MinLength(32)
+    @MaxLength(128)
+    idempotencyKey: string;
+}

package/src/rules/dtos/datalake/EvaluationExecutionResponse.ts

@@ -0,0 +1,7 @@
+import { PopulationExecutionStatusEnum } from '../../enums/PopulationExecutionStatusEnum';
+
+/** Respuesta de `POST /evaluate/executions`. */
+export class EvaluationExecutionResponse {
+    executionId: string;
+    status: PopulationExecutionStatusEnum;
+}

package/src/rules/dtos/datalake/EvaluationExecutionResultsResponse.ts

@@ -0,0 +1,12 @@
+import { PopulationExecutionStatusEnum } from '../../enums/PopulationExecutionStatusEnum';
+import { RulesErrorCodeEnum } from '../../enums/RulesErrorCodeEnum';
+import { RuleEvaluationResult } from '../EvaluateRulesResponse';
+
+/** Pagina de resultados. Sin `nextToken` = última página. `reason` solo si `status` es `FAILED`. */
+export class EvaluationExecutionResultsResponse {
+    executionId: string;
+    status: PopulationExecutionStatusEnum;
+    results: RuleEvaluationResult[];
+    nextToken?: string;
+    reason?: RulesErrorCodeEnum;
+}

package/src/rules/dtos/datalake/EvaluationResultsRequest.ts

@@ -0,0 +1,46 @@
+import { Expose, Type } from 'class-transformer';
+import { ArrayMaxSize, ArrayMinSize, IsArray, IsObject, IsOptional, IsString, Matches, ValidateNested } from 'class-validator';
+import { InputField } from '../../../dynamicForm/dtos/InputField';
+import { RETURN_FIELD_ID_PATTERN, RULES_MAX_INPUT_CONTRACT, RULES_MAX_RETURN_FIELDS } from '../../constants/RulesLimits';
+import { RuleToEvaluate } from '../EvaluateRulesRequest';
+
+/** `POST /evaluate/executions/{id}/results`: pagina de resultados. Reglas, ítems e `inputContract` deben ser los del inicio. */
+export class EvaluationResultsRequest {
+    @Expose()
+    @IsOptional()
+    @IsString()
+    consumer?: string;
+
+    @Expose()
+    @IsArray()
+    @IsString({ each: true })
+    items: string[];
+
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayMinSize(1)
+    @ArrayMaxSize(10)
+    @ValidateNested({ each: true })
+    @Type(() => RuleToEvaluate)
+    rules?: RuleToEvaluate[];
+
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayMaxSize(RULES_MAX_INPUT_CONTRACT)
+    @IsObject({ each: true })
+    inputContract?: InputField[];
+
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayMaxSize(RULES_MAX_RETURN_FIELDS)
+    @Matches(RETURN_FIELD_ID_PATTERN, { each: true })
+    returnFields?: string[];
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    nextToken?: string;
+}

package/src/rules/dtos/datalake/ReturnFieldsCatalogResponse.ts

@@ -0,0 +1,19 @@
+import { RulesValueTypeEnum } from '../../enums/RulesValueTypeEnum';
+
+/** Un campo del catálogo que se puede devolver (`GET /return-fields`). */
+export class ReturnableFieldResponse {
+    /** `fuente:campo`. */
+    id: string;
+    source: string;
+    field: string;
+    label: string;
+    description: string;
+    valueType: RulesValueTypeEnum;
+    datalakeCompatible: boolean;
+}
+
+export class ReturnFieldsCatalogResponse {
+    /** `false` si el datalake no está disponible en el ambiente. */
+    available: boolean;
+    fields: ReturnableFieldResponse[];
+}

package/src/rules/dtos/population/SegmentTableSchemaResponse.ts

@@ -6,6 +6,8 @@ export class SegmentColumnSchemaResponse {
     root?: string;
     type: string;
     isDate: boolean;
+    /** La hoja está detrás de al menos un `array<struct>`: semántica de elemento (`any_match`). */
+    inArray?: boolean;
     operators: SegmentOperatorEnum[];
 }
 

package/src/rules/enums/EvaluationStrategyEnum.ts

@@ -0,0 +1,5 @@
+/** Cómo evalúa el central una regla: `LIVE` (resolvers en vivo, default) o `DATALAKE` (una query Athena por lote). */
+export enum EvaluationStrategyEnum {
+    LIVE = 'LIVE',
+    DATALAKE = 'DATALAKE',
+}

package/src/rules/enums/RulesErrorCodeEnum.ts

@@ -4,4 +4,14 @@ export enum RulesErrorCodeEnum {
     DUPLICATE_SOURCE_IN_ITEMS = 'DUPLICATE_SOURCE_IN_ITEMS',
     TOO_MANY_SUBJECTS = 'TOO_MANY_SUBJECTS',
     VALIDATION_ERROR = 'VALIDATION_ERROR',
+    /** 400: la regla usa `params`, o una tabla que el campo necesita no existe en el ambiente. */
+    RULE_NOT_DATALAKE_COMPATIBLE = 'RULE_NOT_DATALAKE_COMPATIBLE',
+    /** 503: el datalake no está disponible. */
+    DATALAKE_UNAVAILABLE = 'DATALAKE_UNAVAILABLE',
+    /** La query del datalake terminó en error. */
+    DATALAKE_EVALUATION_FAILED = 'DATALAKE_EVALUATION_FAILED',
+    /** La query del datalake superó el tiempo de espera (reintentable). */
+    DATALAKE_EVALUATION_TIMEOUT = 'DATALAKE_EVALUATION_TIMEOUT',
+    /** 400: un id de `returnFields` no existe en el catálogo ni en el esquema del datalake. */
+    UNKNOWN_RETURN_FIELD = 'UNKNOWN_RETURN_FIELD',
 }

package/src/rules/index.ts

@@ -49,3 +49,11 @@ export * from './dtos/population/PopulationTestResponse';
 export * from './dtos/population/PopulationExecutionRequest';
 export * from './dtos/population/PopulationExecutionResponse';
 export * from './dtos/population/PopulationExecutionPageResponse';
+
+//Evaluacion DATALAKE, campos devueltos y ejecucion asincrona
+export * from './enums/EvaluationStrategyEnum';
+export * from './dtos/datalake/EvaluationExecutionRequest';
+export * from './dtos/datalake/EvaluationExecutionResponse';
+export * from './dtos/datalake/EvaluationResultsRequest';
+export * from './dtos/datalake/EvaluationExecutionResultsResponse';
+export * from './dtos/datalake/ReturnFieldsCatalogResponse';