@fiado/type-kit 3.540.0 → 3.542.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/type-kit",
-  "version": "3.540.0",
+  "version": "3.542.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

package/src/card/dtos/CardAuditInfo.ts

@@ -0,0 +1,20 @@
+import { CardAuditActorType } from "../enums/CardAuditActorType";
+import { Status } from "../enums/Status";
+
+/**
+ * Traza aditiva del último cambio de una tarjeta. Se guarda en `createdBy` (una sola vez, al
+ * crear la fila) y en `updatedBy` (se reescribe en cada cambio). El histórico completo vive en el
+ * datalake, no aquí. Las filas anteriores a este campo simplemente no lo traen.
+ */
+export interface CardAuditInfo {
+    actorType: CardAuditActorType;
+    /** email (BACKOFFICE/AGENT), "<proveedor>:<event_type>" (WEBHOOK), componente (SYSTEM). Vacío para USER. */
+    actorId?: string;
+    /** Operación de negocio: CHANGE_STATUS, ACTIVATE, CREATE, REPLACE, SHIPPING_UPDATE, PIN_UPDATE, ... */
+    action: string;
+    /** Status anterior y nuevo, solo cuando la operación cambia el status. */
+    from?: Status;
+    to?: Status;
+    /** ISO 8601. */
+    at: string;
+}

package/src/card/enums/CardAuditActorType.ts

@@ -0,0 +1,15 @@
+/**
+ * Quién originó el último cambio de una tarjeta (`createdBy` / `updatedBy`).
+ *
+ * - USER: el dueño desde la app; no lleva actorId porque el directoryId ya está en la fila.
+ * - BACKOFFICE / AGENT: persona con sesión W4; actorId = email del AuthContext.
+ * - WEBHOOK: evento del emisor (CP, Pomelo); actorId = "<proveedor>:<event_type>".
+ * - SYSTEM: proceso interno sin usuario (colas, cron, callbacks); actorId = componente.
+ */
+export enum CardAuditActorType {
+    USER = "USER",
+    BACKOFFICE = "BACKOFFICE",
+    AGENT = "AGENT",
+    WEBHOOK = "WEBHOOK",
+    SYSTEM = "SYSTEM"
+}

package/src/card/index.ts

@@ -78,3 +78,5 @@ export * from './enums/CardReasonStatus'
 export * from './enums/KycReason'
 export * from './enums/PinChangedStatus'
 export * from './constants/LevelOneAutoIssuanceTags';
+export * from './enums/CardAuditActorType';
+export * from './dtos/CardAuditInfo';

package/src/rewardsEligibility/constants/SegmentLimits.ts

@@ -1,5 +1 @@
-/** Identificador SQL permitido para tabla/columna (A§4.3 paso 1): minusculas, digitos y guion bajo; nunca texto libre. */
-export const SEGMENT_IDENTIFIER_PATTERN = /^[a-z_][a-z0-9_]*$/;
-export const SEGMENT_MAX_DAYS = 365;
-export const SEGMENT_MAX_PARAMS = 40;
-export const SEGMENT_MAX_AGGREGATES = 8;
+export * from '../../rules/constants/SegmentLimits';

package/src/rewardsEligibility/dtos/backoffice/segments/PopulationSegmentDefinition.ts

@@ -1,12 +1 @@
-import { Expose, Type } from 'class-transformer';
-import { ArrayMaxSize, ArrayMinSize, IsArray, IsEnum, Matches, ValidateNested } from 'class-validator';
-import { SEGMENT_IDENTIFIER_PATTERN } from '../../../constants/SegmentLimits';
-import { SegmentMatchEnum } from '../../../enums/SegmentMatchEnum';
-import { SegmentGroup } from './SegmentGroup';
-
-/** El constructor tal cual (A§4.1): tabla ancla (una fila -> un directoryid), TODAS/ALGUNA global y grupos con su propio TODAS/ALGUNA. */
-export class PopulationSegmentDefinition {
-    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) baseTable: string;
-    @Expose() @IsEnum(SegmentMatchEnum) match: SegmentMatchEnum;
-    @Expose() @IsArray() @ArrayMinSize(1) @ArrayMaxSize(10) @ValidateNested({ each: true }) @Type(() => SegmentGroup) groups: SegmentGroup[];
-}
+export * from '../../../../rules/dtos/population/PopulationSegmentDefinition';

package/src/rewardsEligibility/dtos/backoffice/segments/SegmentAggregateCondition.ts

@@ -1,22 +1 @@
-import { Expose, Type } from 'class-transformer';
-import { ArrayMaxSize, Equals, IsArray, IsEnum, IsNumber, IsOptional, Matches, ValidateNested } from 'class-validator';
-import { SEGMENT_IDENTIFIER_PATTERN } from '../../../constants/SegmentLimits';
-import { SegmentAggregateFnEnum } from '../../../enums/SegmentAggregateFnEnum';
-import { SegmentConditionKindEnum } from '../../../enums/SegmentConditionKindEnum';
-import { SegmentOperatorEnum } from '../../../enums/SegmentOperatorEnum';
-import { SegmentColumnCondition } from './SegmentColumnCondition';
-import { SegmentWindow } from './SegmentWindow';
-
-/** (b) Agregado con ventana relativa sobre una tabla relacionada (existe / cuenta / suma). `filters` elige QUE cuenta (estados, moneda...). */
-export class SegmentAggregateCondition {
-    @Expose() @Equals(SegmentConditionKindEnum.AGGREGATE) kind: SegmentConditionKindEnum.AGGREGATE;
-    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) table: string;
-    @Expose() @IsEnum(SegmentAggregateFnEnum) fn: SegmentAggregateFnEnum;
-    /** Solo SUM. */
-    @Expose() @IsOptional() @Matches(SEGMENT_IDENTIFIER_PATTERN) column?: string;
-    /** COUNT y SUM; EXISTS no lleva. */
-    @Expose() @IsOptional() @IsEnum(SegmentOperatorEnum) op?: SegmentOperatorEnum;
-    @Expose() @IsOptional() @IsNumber() value?: number;
-    @Expose() @ValidateNested() @Type(() => SegmentWindow) window: SegmentWindow;
-    @Expose() @IsArray() @ArrayMaxSize(10) @ValidateNested({ each: true }) @Type(() => SegmentColumnCondition) filters: SegmentColumnCondition[];
-}
+export * from '../../../../rules/dtos/population/SegmentAggregateCondition';

package/src/rewardsEligibility/dtos/backoffice/segments/SegmentColumnCondition.ts

@@ -1,15 +1 @@
-import { Expose } from 'class-transformer';
-import { Equals, IsEnum, IsOptional, Matches } from 'class-validator';
-import { JsonValue } from '../../../../common';
-import { SEGMENT_IDENTIFIER_PATTERN } from '../../../constants/SegmentLimits';
-import { SegmentConditionKindEnum } from '../../../enums/SegmentConditionKindEnum';
-import { SegmentOperatorEnum } from '../../../enums/SegmentOperatorEnum';
-
-/** (a) Columna de una tabla unida por `directoryid`. El tipo de `value` (escalar, lista o `{days}`) lo valida el compilador contra el tipo de Glue. */
-export class SegmentColumnCondition {
-    @Expose() @Equals(SegmentConditionKindEnum.COLUMN) kind: SegmentConditionKindEnum.COLUMN;
-    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) table: string;
-    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) column: string;
-    @Expose() @IsEnum(SegmentOperatorEnum) op: SegmentOperatorEnum;
-    @Expose() @IsOptional() value?: JsonValue;
-}
+export * from '../../../../rules/dtos/population/SegmentColumnCondition';

package/src/rewardsEligibility/dtos/backoffice/segments/SegmentGroup.ts

@@ -1,27 +1 @@
-import { Expose, Type } from 'class-transformer';
-import { ArrayMaxSize, ArrayMinSize, IsArray, IsEnum, ValidateNested } from 'class-validator';
-import { SegmentConditionKindEnum } from '../../../enums/SegmentConditionKindEnum';
-import { SegmentMatchEnum } from '../../../enums/SegmentMatchEnum';
-import { SegmentAggregateCondition } from './SegmentAggregateCondition';
-import { SegmentColumnCondition } from './SegmentColumnCondition';
-
-export type SegmentCondition = SegmentColumnCondition | SegmentAggregateCondition;
-
-export class SegmentGroup {
-    @Expose() @IsEnum(SegmentMatchEnum) match: SegmentMatchEnum;
-
-    /** `kind` decide la clase; un `kind` desconocido NO se instancia y la validacion lo rechaza (el objeto queda sin `@Equals` valido). */
-    @Expose()
-    @IsArray() @ArrayMinSize(1) @ArrayMaxSize(20) @ValidateNested({ each: true })
-    @Type(() => Object, {
-        keepDiscriminatorProperty: true,
-        discriminator: {
-            property: 'kind',
-            subTypes: [
-                { value: SegmentColumnCondition, name: SegmentConditionKindEnum.COLUMN },
-                { value: SegmentAggregateCondition, name: SegmentConditionKindEnum.AGGREGATE },
-            ],
-        },
-    })
-    conditions: SegmentCondition[];
-}
+export * from '../../../../rules/dtos/population/SegmentGroup';

package/src/rewardsEligibility/dtos/backoffice/segments/SegmentParam.ts

@@ -1,11 +1 @@
-import { SegmentParamSourceEnum } from '../../../enums/SegmentParamSourceEnum';
-import { SegmentParamTypeEnum } from '../../../enums/SegmentParamTypeEnum';
-
-/** Un `?` del SQL, en orden. LITERAL lleva `value` como texto canonico; REFERENCE_AT_MINUS_DAYS lleva `days`. */
-export class SegmentParam {
-    name: string;
-    type: SegmentParamTypeEnum;
-    source: SegmentParamSourceEnum;
-    value?: string;
-    days?: number;
-}
+export * from '../../../../rules/dtos/population/SegmentParam';

package/src/rewardsEligibility/dtos/backoffice/segments/SegmentSchemaResponse.ts

@@ -1,11 +1 @@
-export class SegmentSchemaTableResponse {
-    table: string;
-    joinKey: string;
-    columnCount: number;
-}
-
-/** `available: false` = ambiente sin datalake accesible: el constructor muestra "no disponible". */
-export class SegmentSchemaResponse {
-    available: boolean;
-    tables: SegmentSchemaTableResponse[];
-}
+export * from '../../../../rules/dtos/population/SegmentSchemaResponse';

package/src/rewardsEligibility/dtos/backoffice/segments/SegmentTableSchemaResponse.ts

@@ -1,14 +1 @@
-import { SegmentOperatorEnum } from '../../../enums/SegmentOperatorEnum';
-
-export class SegmentColumnSchemaResponse {
-    name: string;
-    type: string;
-    isDate: boolean;
-    operators: SegmentOperatorEnum[];
-}
-
-export class SegmentTableSchemaResponse {
-    table: string;
-    joinKey: string;
-    columns: SegmentColumnSchemaResponse[];
-}
+export * from '../../../../rules/dtos/population/SegmentTableSchemaResponse';

package/src/rewardsEligibility/dtos/backoffice/segments/SegmentUsedColumn.ts

@@ -1,5 +1 @@
-export class SegmentUsedColumn {
-    table: string;
-    column: string;
-    type: string;
-}
+export * from '../../../../rules/dtos/population/SegmentUsedColumn';

package/src/rewardsEligibility/dtos/backoffice/segments/SegmentWindow.ts

@@ -1,9 +1 @@
-import { Expose } from 'class-transformer';
-import { IsInt, Matches, Max, Min } from 'class-validator';
-import { SEGMENT_IDENTIFIER_PATTERN, SEGMENT_MAX_DAYS } from '../../../constants/SegmentLimits';
-
-/** Ventana relativa [referenceAt - days, referenceAt) sobre una columna de fecha (A§4.1). */
-export class SegmentWindow {
-    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) dateColumn: string;
-    @Expose() @IsInt() @Min(1) @Max(SEGMENT_MAX_DAYS) days: number;
-}
+export * from '../../../../rules/dtos/population/SegmentWindow';

package/src/rewardsEligibility/enums/SegmentAggregateFnEnum.ts

@@ -1,5 +1 @@
-export enum SegmentAggregateFnEnum {
-    EXISTS = 'EXISTS',
-    COUNT = 'COUNT',
-    SUM = 'SUM',
-}
+export * from '../../rules/enums/SegmentAggregateFnEnum';

package/src/rewardsEligibility/enums/SegmentConditionKindEnum.ts

@@ -1,4 +1 @@
-export enum SegmentConditionKindEnum {
-    COLUMN = 'COLUMN',
-    AGGREGATE = 'AGGREGATE',
-}
+export * from '../../rules/enums/SegmentConditionKindEnum';

package/src/rewardsEligibility/enums/SegmentMatchEnum.ts

@@ -1,4 +1 @@
-export enum SegmentMatchEnum {
-    ALL = 'ALL',
-    ANY = 'ANY',
-}
+export * from '../../rules/enums/SegmentMatchEnum';

package/src/rewardsEligibility/enums/SegmentOperatorEnum.ts

@@ -1,16 +1 @@
-export enum SegmentOperatorEnum {
-    EQUALS = 'EQUALS',
-    NOT_EQUALS = 'NOT_EQUALS',
-    IN = 'IN',
-    NOT_IN = 'NOT_IN',
-    IS_NULL = 'IS_NULL',
-    IS_NOT_NULL = 'IS_NOT_NULL',
-    GT = 'GT',
-    GTE = 'GTE',
-    LT = 'LT',
-    LTE = 'LTE',
-    CONTAINS = 'CONTAINS',
-    ANY_IN = 'ANY_IN',
-    WITHIN_LAST_DAYS = 'WITHIN_LAST_DAYS',
-    NOT_WITHIN_LAST_DAYS = 'NOT_WITHIN_LAST_DAYS',
-}
+export * from '../../rules/enums/SegmentOperatorEnum';

package/src/rewardsEligibility/enums/SegmentParamSourceEnum.ts

@@ -1,5 +1 @@
-export enum SegmentParamSourceEnum {
-    LITERAL = 'LITERAL',
-    REFERENCE_AT = 'REFERENCE_AT',
-    REFERENCE_AT_MINUS_DAYS = 'REFERENCE_AT_MINUS_DAYS',
-}
+export * from '../../rules/enums/SegmentParamSourceEnum';

package/src/rewardsEligibility/enums/SegmentParamTypeEnum.ts

@@ -1,7 +1 @@
-export enum SegmentParamTypeEnum {
-    STRING = 'STRING',
-    INTEGER = 'INTEGER',
-    DECIMAL = 'DECIMAL',
-    BOOLEAN = 'BOOLEAN',
-    TIMESTAMP = 'TIMESTAMP',
-}
+export * from '../../rules/enums/SegmentParamTypeEnum';

package/src/rules/constants/SegmentLimits.ts

@@ -0,0 +1,5 @@
+/** Identificador SQL permitido para tabla/columna (A§4.3 paso 1): minusculas, digitos y guion bajo; nunca texto libre. */
+export const SEGMENT_IDENTIFIER_PATTERN = /^[a-z_][a-z0-9_]*$/;
+export const SEGMENT_MAX_DAYS = 365;
+export const SEGMENT_MAX_PARAMS = 40;
+export const SEGMENT_MAX_AGGREGATES = 8;

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

@@ -0,0 +1,9 @@
+import { Expose, Type } from 'class-transformer';
+import { IsDefined, IsOptional, IsString, ValidateNested } from 'class-validator';
+import { PopulationSegmentDefinition } from './PopulationSegmentDefinition';
+
+/** Compila una definicion a SQL parametrizado (POST /population/compile). `consumer` solo para logs/metricas. */
+export class PopulationCompileRequest {
+    @Expose() @IsOptional() @IsString() consumer?: string;
+    @Expose() @IsDefined() @ValidateNested() @Type(() => PopulationSegmentDefinition) definition: PopulationSegmentDefinition;
+}

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

@@ -0,0 +1,10 @@
+import { SegmentParam } from './SegmentParam';
+import { SegmentUsedColumn } from './SegmentUsedColumn';
+
+export class PopulationCompileResponse {
+    sql: string;
+    params: SegmentParam[];
+    usedColumns: SegmentUsedColumn[];
+    humanSummary: string;
+    definitionHash: string;
+}

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

@@ -0,0 +1,11 @@
+import { PopulationErrorCodeEnum } from '../../enums/PopulationErrorCodeEnum';
+import { PopulationExecutionStatusEnum } from '../../enums/PopulationExecutionStatusEnum';
+
+/** Pagina de hasta 1000 ids. Sin `nextToken` = ultima pagina. */
+export class PopulationExecutionPageResponse {
+    executionId: string;
+    status: PopulationExecutionStatusEnum;
+    ids: string[];
+    nextToken?: string;
+    reason?: PopulationErrorCodeEnum;
+}

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

@@ -0,0 +1,13 @@
+import { Expose, Type } from 'class-transformer';
+import { IsDefined, IsISO8601, IsNotEmpty, IsOptional, IsString, MaxLength, MinLength, ValidateNested } from 'class-validator';
+import { PopulationSegmentDefinition } from './PopulationSegmentDefinition';
+
+/** Inicia una ejecucion de poblacion (POST /population/executions). El central recompila; `expectedSql` activa G3 (SEGMENT_SCHEMA_DRIFT). */
+export class PopulationExecutionRequest {
+    @Expose() @IsOptional() @IsString() consumer?: string;
+    @Expose() @IsDefined() @ValidateNested() @Type(() => PopulationSegmentDefinition) definition: PopulationSegmentDefinition;
+    @Expose() @IsISO8601({ strict: true }) referenceAt: string;
+    @Expose() @IsString() @MinLength(32) @MaxLength(128) idempotencyKey: string;
+    @Expose() @IsOptional() @IsString() @IsNotEmpty() expectedSql?: string;
+    @Expose() @IsOptional() @IsString() @MinLength(1) @MaxLength(256) afterDirectoryId?: string;
+}

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

@@ -0,0 +1,6 @@
+import { PopulationExecutionStatusEnum } from '../../enums/PopulationExecutionStatusEnum';
+
+export class PopulationExecutionResponse {
+    executionId: string;
+    status: PopulationExecutionStatusEnum;
+}

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

@@ -0,0 +1,12 @@
+import { Expose, Type } from 'class-transformer';
+import { ArrayMaxSize, ArrayMinSize, IsArray, IsEnum, Matches, ValidateNested } from 'class-validator';
+import { SEGMENT_IDENTIFIER_PATTERN } from '../../constants/SegmentLimits';
+import { SegmentMatchEnum } from '../../enums/SegmentMatchEnum';
+import { SegmentGroup } from './SegmentGroup';
+
+/** El constructor tal cual (A§4.1): tabla ancla (una fila -> un directoryid), TODAS/ALGUNA global y grupos con su propio TODAS/ALGUNA. */
+export class PopulationSegmentDefinition {
+    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) baseTable: string;
+    @Expose() @IsEnum(SegmentMatchEnum) match: SegmentMatchEnum;
+    @Expose() @IsArray() @ArrayMinSize(1) @ArrayMaxSize(10) @ValidateNested({ each: true }) @Type(() => SegmentGroup) groups: SegmentGroup[];
+}

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

@@ -0,0 +1,10 @@
+import { Expose, Type } from 'class-transformer';
+import { IsDefined, IsISO8601, IsOptional, IsString, ValidateNested } from 'class-validator';
+import { PopulationSegmentDefinition } from './PopulationSegmentDefinition';
+
+/** Prueba sin estado de una definicion (POST /population/tests). `referenceAt` ISO-8601 con zona; por defecto, ahora. */
+export class PopulationTestRequest {
+    @Expose() @IsOptional() @IsString() consumer?: string;
+    @Expose() @IsDefined() @ValidateNested() @Type(() => PopulationSegmentDefinition) definition: PopulationSegmentDefinition;
+    @Expose() @IsOptional() @IsISO8601({ strict: true }) referenceAt?: string;
+}

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

@@ -0,0 +1,29 @@
+import { PopulationErrorCodeEnum } from '../../enums/PopulationErrorCodeEnum';
+import { PopulationTestStatusEnum } from '../../enums/PopulationTestStatusEnum';
+import { SegmentParam } from './SegmentParam';
+
+export class PopulationTestResultResponse {
+    count: number;
+    sampleIds: string[];
+    bytesScanned: number;
+    durationMs: number;
+}
+
+export class PopulationTestErrorResponse {
+    code: PopulationErrorCodeEnum;
+    message: string;
+}
+
+/** `queryExecutionId` sale del count (lastTest de rewards). Estado RUNNING: el cliente reconsulta por `testId`. */
+export class PopulationTestResponse {
+    testId: string;
+    status: PopulationTestStatusEnum;
+    referenceAt: string;
+    definitionHash: string;
+    humanSummary: string;
+    sql: string;
+    params: SegmentParam[];
+    queryExecutionId?: string;
+    result?: PopulationTestResultResponse;
+    errors?: PopulationTestErrorResponse[];
+}

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

@@ -0,0 +1,22 @@
+import { Expose, Type } from 'class-transformer';
+import { ArrayMaxSize, Equals, IsArray, IsEnum, IsNumber, IsOptional, Matches, ValidateNested } from 'class-validator';
+import { SEGMENT_IDENTIFIER_PATTERN } from '../../constants/SegmentLimits';
+import { SegmentAggregateFnEnum } from '../../enums/SegmentAggregateFnEnum';
+import { SegmentConditionKindEnum } from '../../enums/SegmentConditionKindEnum';
+import { SegmentOperatorEnum } from '../../enums/SegmentOperatorEnum';
+import { SegmentColumnCondition } from './SegmentColumnCondition';
+import { SegmentWindow } from './SegmentWindow';
+
+/** (b) Agregado con ventana relativa sobre una tabla relacionada (existe / cuenta / suma). `filters` elige QUE cuenta (estados, moneda...). */
+export class SegmentAggregateCondition {
+    @Expose() @Equals(SegmentConditionKindEnum.AGGREGATE) kind: SegmentConditionKindEnum.AGGREGATE;
+    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) table: string;
+    @Expose() @IsEnum(SegmentAggregateFnEnum) fn: SegmentAggregateFnEnum;
+    /** Solo SUM. */
+    @Expose() @IsOptional() @Matches(SEGMENT_IDENTIFIER_PATTERN) column?: string;
+    /** COUNT y SUM; EXISTS no lleva. */
+    @Expose() @IsOptional() @IsEnum(SegmentOperatorEnum) op?: SegmentOperatorEnum;
+    @Expose() @IsOptional() @IsNumber() value?: number;
+    @Expose() @ValidateNested() @Type(() => SegmentWindow) window: SegmentWindow;
+    @Expose() @IsArray() @ArrayMaxSize(10) @ValidateNested({ each: true }) @Type(() => SegmentColumnCondition) filters: SegmentColumnCondition[];
+}

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

@@ -0,0 +1,15 @@
+import { Expose } from 'class-transformer';
+import { Equals, IsEnum, IsOptional, Matches } from 'class-validator';
+import { JsonValue } from '../../../common';
+import { SEGMENT_IDENTIFIER_PATTERN } from '../../constants/SegmentLimits';
+import { SegmentConditionKindEnum } from '../../enums/SegmentConditionKindEnum';
+import { SegmentOperatorEnum } from '../../enums/SegmentOperatorEnum';
+
+/** (a) Columna de una tabla unida por `directoryid`. El tipo de `value` (escalar, lista o `{days}`) lo valida el compilador contra el tipo de Glue. */
+export class SegmentColumnCondition {
+    @Expose() @Equals(SegmentConditionKindEnum.COLUMN) kind: SegmentConditionKindEnum.COLUMN;
+    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) table: string;
+    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) column: string;
+    @Expose() @IsEnum(SegmentOperatorEnum) op: SegmentOperatorEnum;
+    @Expose() @IsOptional() value?: JsonValue;
+}

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

@@ -0,0 +1,27 @@
+import { Expose, Type } from 'class-transformer';
+import { ArrayMaxSize, ArrayMinSize, IsArray, IsEnum, ValidateNested } from 'class-validator';
+import { SegmentConditionKindEnum } from '../../enums/SegmentConditionKindEnum';
+import { SegmentMatchEnum } from '../../enums/SegmentMatchEnum';
+import { SegmentAggregateCondition } from './SegmentAggregateCondition';
+import { SegmentColumnCondition } from './SegmentColumnCondition';
+
+export type SegmentCondition = SegmentColumnCondition | SegmentAggregateCondition;
+
+export class SegmentGroup {
+    @Expose() @IsEnum(SegmentMatchEnum) match: SegmentMatchEnum;
+
+    /** `kind` decide la clase; un `kind` desconocido NO se instancia y la validacion lo rechaza (el objeto queda sin `@Equals` valido). */
+    @Expose()
+    @IsArray() @ArrayMinSize(1) @ArrayMaxSize(20) @ValidateNested({ each: true })
+    @Type(() => Object, {
+        keepDiscriminatorProperty: true,
+        discriminator: {
+            property: 'kind',
+            subTypes: [
+                { value: SegmentColumnCondition, name: SegmentConditionKindEnum.COLUMN },
+                { value: SegmentAggregateCondition, name: SegmentConditionKindEnum.AGGREGATE },
+            ],
+        },
+    })
+    conditions: SegmentCondition[];
+}

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

@@ -0,0 +1,11 @@
+import { SegmentParamSourceEnum } from '../../enums/SegmentParamSourceEnum';
+import { SegmentParamTypeEnum } from '../../enums/SegmentParamTypeEnum';
+
+/** Un `?` del SQL, en orden. LITERAL lleva `value` como texto canonico; REFERENCE_AT_MINUS_DAYS lleva `days`. */
+export class SegmentParam {
+    name: string;
+    type: SegmentParamTypeEnum;
+    source: SegmentParamSourceEnum;
+    value?: string;
+    days?: number;
+}

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

@@ -0,0 +1,11 @@
+export class SegmentSchemaTableResponse {
+    table: string;
+    joinKey: string;
+    columnCount: number;
+}
+
+/** `available: false` = ambiente sin datalake accesible: el constructor muestra "no disponible". */
+export class SegmentSchemaResponse {
+    available: boolean;
+    tables: SegmentSchemaTableResponse[];
+}

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

@@ -0,0 +1,14 @@
+import { SegmentOperatorEnum } from '../../enums/SegmentOperatorEnum';
+
+export class SegmentColumnSchemaResponse {
+    name: string;
+    type: string;
+    isDate: boolean;
+    operators: SegmentOperatorEnum[];
+}
+
+export class SegmentTableSchemaResponse {
+    table: string;
+    joinKey: string;
+    columns: SegmentColumnSchemaResponse[];
+}

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

@@ -0,0 +1,5 @@
+export class SegmentUsedColumn {
+    table: string;
+    column: string;
+    type: string;
+}

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

@@ -0,0 +1,9 @@
+import { Expose } from 'class-transformer';
+import { IsInt, Matches, Max, Min } from 'class-validator';
+import { SEGMENT_IDENTIFIER_PATTERN, SEGMENT_MAX_DAYS } from '../../constants/SegmentLimits';
+
+/** Ventana relativa [referenceAt - days, referenceAt) sobre una columna de fecha (A§4.1). */
+export class SegmentWindow {
+    @Expose() @Matches(SEGMENT_IDENTIFIER_PATTERN) dateColumn: string;
+    @Expose() @IsInt() @Min(1) @Max(SEGMENT_MAX_DAYS) days: number;
+}

package/src/rules/enums/PopulationErrorCodeEnum.ts

@@ -0,0 +1,12 @@
+/** Codigos de error del canal de poblacion. Los 8 primeros coinciden con SegmentErrorCodeEnum. */
+export enum PopulationErrorCodeEnum {
+    SEGMENT_INVALID = 'SEGMENT_INVALID',
+    SEGMENT_BLOCKED_COLUMN = 'SEGMENT_BLOCKED_COLUMN',
+    SEGMENT_SCHEMA_DRIFT = 'SEGMENT_SCHEMA_DRIFT',
+    SEGMENT_BYTES_EXCEEDED = 'SEGMENT_BYTES_EXCEEDED',
+    SEGMENT_QUERY_FAILED = 'SEGMENT_QUERY_FAILED',
+    SEGMENT_DATALAKE_UNAVAILABLE = 'SEGMENT_DATALAKE_UNAVAILABLE',
+    SEGMENT_DATALAKE_UNAVAILABLE_IN_ENV = 'SEGMENT_DATALAKE_UNAVAILABLE_IN_ENV',
+    SEGMENT_EXECUTION_NOT_FOUND = 'SEGMENT_EXECUTION_NOT_FOUND',
+    SEGMENT_NEXT_TOKEN_EXPIRED = 'SEGMENT_NEXT_TOKEN_EXPIRED',
+}

package/src/rules/enums/PopulationExecutionStatusEnum.ts

@@ -0,0 +1,6 @@
+export enum PopulationExecutionStatusEnum {
+    RUNNING = 'RUNNING',
+    SUCCEEDED = 'SUCCEEDED',
+    FAILED = 'FAILED',
+    CANCELLED = 'CANCELLED',
+}

package/src/rules/enums/PopulationTestStatusEnum.ts

@@ -0,0 +1,5 @@
+export enum PopulationTestStatusEnum {
+    RUNNING = 'RUNNING',
+    PASSED = 'PASSED',
+    FAILED = 'FAILED',
+}

package/src/rules/enums/SegmentAggregateFnEnum.ts

@@ -0,0 +1,5 @@
+export enum SegmentAggregateFnEnum {
+    EXISTS = 'EXISTS',
+    COUNT = 'COUNT',
+    SUM = 'SUM',
+}

package/src/rules/enums/SegmentConditionKindEnum.ts

@@ -0,0 +1,4 @@
+export enum SegmentConditionKindEnum {
+    COLUMN = 'COLUMN',
+    AGGREGATE = 'AGGREGATE',
+}

package/src/rules/enums/SegmentMatchEnum.ts

@@ -0,0 +1,4 @@
+export enum SegmentMatchEnum {
+    ALL = 'ALL',
+    ANY = 'ANY',
+}

package/src/rules/enums/SegmentOperatorEnum.ts

@@ -0,0 +1,16 @@
+export enum SegmentOperatorEnum {
+    EQUALS = 'EQUALS',
+    NOT_EQUALS = 'NOT_EQUALS',
+    IN = 'IN',
+    NOT_IN = 'NOT_IN',
+    IS_NULL = 'IS_NULL',
+    IS_NOT_NULL = 'IS_NOT_NULL',
+    GT = 'GT',
+    GTE = 'GTE',
+    LT = 'LT',
+    LTE = 'LTE',
+    CONTAINS = 'CONTAINS',
+    ANY_IN = 'ANY_IN',
+    WITHIN_LAST_DAYS = 'WITHIN_LAST_DAYS',
+    NOT_WITHIN_LAST_DAYS = 'NOT_WITHIN_LAST_DAYS',
+}

package/src/rules/enums/SegmentParamSourceEnum.ts

@@ -0,0 +1,5 @@
+export enum SegmentParamSourceEnum {
+    LITERAL = 'LITERAL',
+    REFERENCE_AT = 'REFERENCE_AT',
+    REFERENCE_AT_MINUS_DAYS = 'REFERENCE_AT_MINUS_DAYS',
+}

package/src/rules/enums/SegmentParamTypeEnum.ts

@@ -0,0 +1,7 @@
+export enum SegmentParamTypeEnum {
+    STRING = 'STRING',
+    INTEGER = 'INTEGER',
+    DECIMAL = 'DECIMAL',
+    BOOLEAN = 'BOOLEAN',
+    TIMESTAMP = 'TIMESTAMP',
+}