@fiado/type-kit 3.594.0 → 3.596.0

package/_test_/unit/rewardsEligibility/catalogDtos.test.ts

@@ -11,6 +11,7 @@ describe('DTOs de catálogos (forma)', () => {
                 fields: [{ field: 'accountAgeDays', label: 'Antigüedad', valueType: RuleValueTypeEnum.NUMBER, operators: ['GT', 'LTE'] }],
             }],
             operators: { GT: '>', LTE: '≤' },
+            relations: [],
         };
         expect(catalog.sources[0]?.fields[0]?.valueType).toBe('NUMBER');
     });

package/_test_/unit/rules/relationContract.test.ts

@@ -0,0 +1,84 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import {
+    RETURN_FIELD_ID_PATTERN,
+    RULES_EXPOSE_AS_PATTERN,
+    RULES_MAX_RELATION_BLOCKS,
+    RULES_MAX_RELATION_DEPTH,
+    RULES_MAX_WITHIN_LAST_DAYS,
+    RULES_RELATION_NAME_PATTERN,
+    RulesCatalogResponse,
+    RulesRelationCardinalityEnum,
+    RulesRelationTargetEnum,
+    relationReturnFieldId,
+} from '../../../src/rules';
+import {
+    RuleCatalogResponse,
+    RulesRelationCardinalityEnum as EligibilityCardinality,
+    RulesRelationTargetEnum as EligibilityTarget,
+} from '../../../src/rewardsEligibility';
+
+describe('contrato de relaciones (rules)', () => {
+    it('relationReturnFieldId concatena relación:exposeAs y cumple RETURN_FIELD_ID_PATTERN', () => {
+        const id = relationReturnFieldId('referidos', 'referidos_mx_count');
+        expect(id).toBe('referidos:referidos_mx_count');
+        expect(RETURN_FIELD_ID_PATTERN.test(id)).toBe(true);
+    });
+
+    it('RULES_RELATION_NAME_PATTERN acepta minúsculas con guiones y rechaza el resto', () => {
+        expect(RULES_RELATION_NAME_PATTERN.test('referidos')).toBe(true);
+        expect(RULES_RELATION_NAME_PATTERN.test('mi-relacion2')).toBe(true);
+        expect(RULES_RELATION_NAME_PATTERN.test('Referidos')).toBe(false);
+        expect(RULES_RELATION_NAME_PATTERN.test('mx count')).toBe(false);
+    });
+
+    it('RULES_EXPOSE_AS_PATTERN acepta letras/dígitos/guion bajo y rechaza espacios', () => {
+        expect(RULES_EXPOSE_AS_PATTERN.test('referidos_mx_count')).toBe(true);
+        expect(RULES_EXPOSE_AS_PATTERN.test('Referidos')).toBe(true);
+        expect(RULES_EXPOSE_AS_PATTERN.test('mx count')).toBe(false);
+        expect(RULES_EXPOSE_AS_PATTERN.test('1abc')).toBe(false);
+    });
+
+    it('topes fijados por el plan', () => {
+        expect(RULES_MAX_RELATION_DEPTH).toBe(2);
+        expect(RULES_MAX_RELATION_BLOCKS).toBe(5);
+        expect(RULES_MAX_WITHIN_LAST_DAYS).toBe(365);
+    });
+
+    it('valores de los enums', () => {
+        expect(RulesRelationCardinalityEnum).toEqual({ ONE: 'ONE', MANY: 'MANY' });
+        expect(RulesRelationTargetEnum).toEqual({ PERSON: 'PERSON', RECORD: 'RECORD' });
+    });
+
+    it('plainToInstance conserva relations del catálogo de rules', () => {
+        const parsed = plainToInstance(RulesCatalogResponse, {
+            items: [],
+            operators: { WITHIN_LAST_DAYS: 'en los últimos N días' },
+            relations: [
+                { name: 'referidos', label: 'Referidos', description: 'd', cardinality: 'MANY', target: 'PERSON', maxRelated: 500 },
+                { name: 'creditos', label: 'Créditos', description: 'd', cardinality: 'MANY', target: 'RECORD', fields: [] },
+            ],
+        });
+        expect(parsed.relations).toHaveLength(2);
+        expect(parsed.relations[0].cardinality).toBe(RulesRelationCardinalityEnum.MANY);
+        expect(parsed.relations[0].maxRelated).toBe(500);
+        expect(parsed.relations[1].target).toBe(RulesRelationTargetEnum.RECORD);
+    });
+});
+
+describe('contrato de relaciones (rewardsEligibility)', () => {
+    it('reutiliza los enums de rules', () => {
+        expect(EligibilityCardinality).toBe(RulesRelationCardinalityEnum);
+        expect(EligibilityTarget).toBe(RulesRelationTargetEnum);
+    });
+
+    it('plainToInstance conserva relations del catálogo de eligibility', () => {
+        const parsed = plainToInstance(RuleCatalogResponse, {
+            sources: [],
+            operators: {},
+            relations: [{ name: 'referidor', label: 'Referidor', description: 'd', cardinality: 'ONE', target: 'PERSON' }],
+        });
+        expect(parsed.relations[0].cardinality).toBe(EligibilityCardinality.ONE);
+        expect(parsed.relations[0].maxRelated).toBeUndefined();
+    });
+});

package/_test_/unit/rules/traceNested.test.ts

@@ -0,0 +1,115 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import {
+    RulesOutcomeEnum,
+    RulesTraceConditionResponse,
+    RulesTraceGroupResponse,
+    RulesTraceRelatedResponse,
+    RulesTraceRelationResponse,
+    RulesTraceResponse,
+} from '../../../src/rules';
+import {
+    EvaluationOutcomeEnum,
+    TraceConditionResponse,
+    TraceGroupResponse,
+    TraceRelatedResponse,
+    TraceRelationResponse,
+} from '../../../src/rewardsEligibility';
+
+const condition: RulesTraceConditionResponse = {
+    source: 'directory',
+    field: 'country',
+    op: 'EQ',
+    expected: 'MX',
+    actual: 'MX',
+    outcome: RulesOutcomeEnum.MATCH,
+};
+
+const relatedTrace: RulesTraceResponse = {
+    match: 'ALL',
+    outcome: RulesOutcomeEnum.MATCH,
+    groups: [{ match: 'ALL', outcome: RulesOutcomeEnum.MATCH, conditions: [condition] }],
+};
+
+const relatedOne: RulesTraceRelatedResponse = {
+    directoryId: 'dir-1',
+    outcome: RulesOutcomeEnum.MATCH,
+    trace: relatedTrace,
+};
+
+const block: RulesTraceRelationResponse = {
+    kind: 'RELATION',
+    relation: 'referidos',
+    quantifier: { kind: 'COUNT', op: 'GTE', value: 1 },
+    exposeAs: 'referidos_mx_count',
+    outcome: RulesOutcomeEnum.MATCH,
+    matched: 1,
+    errored: 0,
+    total: 1,
+    related: [relatedOne],
+};
+
+describe('trazas anidadas (rules)', () => {
+    it('serializa y deserializa un bloque de relación con relacionado sin pérdida', () => {
+        const group: RulesTraceGroupResponse = {
+            match: 'ALL',
+            outcome: RulesOutcomeEnum.MATCH,
+            conditions: [condition, block],
+        };
+        const roundTrip: RulesTraceGroupResponse = JSON.parse(JSON.stringify(group));
+        expect(roundTrip).toStrictEqual(group);
+    });
+
+    it('el discriminante kind distingue bloque de condición plana', () => {
+        const group: RulesTraceGroupResponse = {
+            match: 'ANY',
+            outcome: RulesOutcomeEnum.MATCH,
+            conditions: [condition, block],
+        };
+        const blocks = group.conditions.filter((n): n is RulesTraceRelationResponse => 'kind' in n && n.kind === 'RELATION');
+        expect(blocks).toHaveLength(1);
+        expect(blocks[0].related[0].trace.groups[0].conditions[0]).toStrictEqual(condition);
+    });
+
+    it('una traza plana de 0.4.1 compila y se conserva igual', () => {
+        const flat: RulesTraceGroupResponse = { match: 'ALL', outcome: RulesOutcomeEnum.MATCH, conditions: [condition] };
+        expect(plainToInstance(RulesTraceGroupResponse, flat)).toEqual(flat);
+    });
+
+    it('un bloque en ERROR lleva error y sin related', () => {
+        const errored: RulesTraceRelationResponse = {
+            kind: 'RELATION',
+            relation: 'referidos',
+            outcome: RulesOutcomeEnum.ERROR,
+            matched: 0,
+            errored: 0,
+            total: 0,
+            related: [],
+            error: { code: 'RELATION_NOT_RESOLVED', message: 'sin resolver' },
+        };
+        expect(JSON.parse(JSON.stringify(errored))).toStrictEqual(errored);
+    });
+});
+
+describe('trazas anidadas (eligibility)', () => {
+    const cond: TraceConditionResponse = {
+        source: 'directory', field: 'country', op: 'EQ', expected: 'MX', actual: 'MX',
+        outcome: EvaluationOutcomeEnum.MATCH,
+    };
+    const related: TraceRelatedResponse = {
+        directoryId: 'dir-1',
+        outcome: EvaluationOutcomeEnum.MATCH,
+        trace: { match: 'ALL', outcome: EvaluationOutcomeEnum.MATCH, groups: [{ match: 'ALL', outcome: EvaluationOutcomeEnum.MATCH, conditions: [cond] }] },
+    };
+    const eBlock: TraceRelationResponse = {
+        kind: 'RELATION', relation: 'referidor',
+        outcome: EvaluationOutcomeEnum.MATCH, matched: 1, errored: 0, total: 1, related: [related],
+    };
+
+    it('serializa un grupo con condición plana y bloque', () => {
+        const group: TraceGroupResponse = { match: 'ALL', outcome: EvaluationOutcomeEnum.MATCH, conditions: [cond, eBlock] };
+        expect(JSON.parse(JSON.stringify(group))).toStrictEqual(JSON.parse(JSON.stringify(group)));
+        const back: TraceGroupResponse = JSON.parse(JSON.stringify(group));
+        expect(back.conditions[1]).toStrictEqual(JSON.parse(JSON.stringify(eBlock)));
+    });
+});

package/_test_/unit/rules/validateNodes.test.ts

@@ -0,0 +1,68 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import {
+    RETURN_FIELD_ID_PATTERN,
+    RulesExposedFieldResponse,
+    RulesNodeErrorCodeEnum,
+    RulesValueTypeEnum,
+    ValidateRulesResponse,
+    relationReturnFieldId,
+} from '../../../src/rules';
+
+const ENGINE_NODE_ERROR_CODES: string[] = [
+    'UNKNOWN_RELATION',
+    'INVALID_RELATION_NODE',
+    'QUANTIFIER_REQUIRED',
+    'QUANTIFIER_NOT_ALLOWED',
+    'INVALID_QUANTIFIER',
+    'SUBJECT_IN_RELATION',
+    'EXPOSE_AS_NOT_ALLOWED',
+    'INVALID_EXPOSE_AS',
+    'DUPLICATE_EXPOSE_AS',
+    'MAX_DEPTH_EXCEEDED',
+    'MAX_BLOCKS_EXCEEDED',
+];
+
+describe('validación de nodos de relación (rules)', () => {
+    it('RulesNodeErrorCodeEnum contiene los 11 códigos del engine, string a string', () => {
+        const values: string[] = Object.values(RulesNodeErrorCodeEnum);
+        ENGINE_NODE_ERROR_CODES.forEach(code => expect(values).toContain(code));
+    });
+
+    it('agrega los códigos del Plan B y cada clave coincide con su valor', () => {
+        expect(RulesNodeErrorCodeEnum.RELATION_SOURCE_NOT_BATCH_CAPABLE).toBe('RELATION_SOURCE_NOT_BATCH_CAPABLE');
+        expect(RulesNodeErrorCodeEnum.MAX_RELATED_EXCEEDED).toBe('MAX_RELATED_EXCEEDED');
+        expect(Object.values(RulesNodeErrorCodeEnum)).toHaveLength(ENGINE_NODE_ERROR_CODES.length + 2);
+        Object.entries(RulesNodeErrorCodeEnum).forEach(([key, value]) => expect(value).toBe(key));
+    });
+
+    it('un ValidateRulesResponse plano serializa con nodeErrors y exposedFields vacíos', () => {
+        const plain = { valid: true, errors: [], nodeErrors: [], exposedFields: [] };
+        const response = plainToInstance(ValidateRulesResponse, plain);
+        expect(JSON.parse(JSON.stringify(response))).toStrictEqual(plain);
+        expect(response.nodeErrors).toStrictEqual([]);
+        expect(response.exposedFields).toStrictEqual([]);
+    });
+
+    it('conserva nodeErrors con path/code/message al deserializar', () => {
+        const response = plainToInstance(ValidateRulesResponse, {
+            valid: false,
+            errors: ['x'],
+            nodeErrors: [{ path: 'groups[0].conditions[1]', code: 'UNKNOWN_RELATION', message: 'no existe' }],
+            exposedFields: [],
+        });
+        expect(response.nodeErrors[0].code).toBe(RulesNodeErrorCodeEnum.UNKNOWN_RELATION);
+        expect(response.nodeErrors[0].path).toBe('groups[0].conditions[1]');
+    });
+
+    it('exposedFields[].id cumple RETURN_FIELD_ID_PATTERN', () => {
+        const field: RulesExposedFieldResponse = {
+            id: relationReturnFieldId('referidos', 'referidos_mx_count'),
+            relation: 'referidos',
+            exposeAs: 'referidos_mx_count',
+            valueType: RulesValueTypeEnum.NUMBER,
+        };
+        expect(RETURN_FIELD_ID_PATTERN.test(field.id)).toBe(true);
+        expect(field.id).toBe('referidos:referidos_mx_count');
+    });
+});

package/bin/directory/index.d.ts

@@ -9,8 +9,8 @@ export * from './dtos/DeleteByDirectoryResponse';
 export * from './dtos/DirectoryAgentsBySponsorRequest';
 export * from './dtos/DirectoryAgentsBySponsorResponse';
 export * from './dtos/DirectoryUserScopeUpdateRequest';
-export * from './dtos/AccountCreatedEventDetail';
 export * from './dtos/External';
 export * from './enums/TypeOfDirectoryId';
 export * from './enums/DirectoryBackofficeStatusEnum';
 export * from './enums/DirectoryUserLifecycleEventTypeEnum';
+export * from './events/AccountCreatedEventDetail';

package/bin/directory/index.js

@@ -26,9 +26,10 @@ __exportStar(require("./dtos/DeleteByDirectoryResponse"), exports);
 __exportStar(require("./dtos/DirectoryAgentsBySponsorRequest"), exports);
 __exportStar(require("./dtos/DirectoryAgentsBySponsorResponse"), exports);
 __exportStar(require("./dtos/DirectoryUserScopeUpdateRequest"), exports);
-__exportStar(require("./dtos/AccountCreatedEventDetail"), exports);
 __exportStar(require("./dtos/External"), exports);
 //enums
 __exportStar(require("./enums/TypeOfDirectoryId"), exports);
 __exportStar(require("./enums/DirectoryBackofficeStatusEnum"), exports);
 __exportStar(require("./enums/DirectoryUserLifecycleEventTypeEnum"), exports);
+//events
+__exportStar(require("./events/AccountCreatedEventDetail"), exports);

package/bin/rewardsEligibility/dtos/backoffice/ResultTraceResponse.d.ts

@@ -21,10 +21,37 @@ export declare class TraceConditionResponse {
         message: string;
     };
 }
+/** Un relacionado evaluado dentro de un bloque de relación, con su traza propia. */
+export declare class TraceRelatedResponse {
+    directoryId: string;
+    outcome: EvaluationOutcomeEnum;
+    trace: ResultTraceResponse;
+}
+/** Un bloque de relación evaluado (ej. «referidos»). Discriminante: `kind: 'RELATION'`. Sin `origin`/`asOf`. */
+export declare class TraceRelationResponse {
+    kind: 'RELATION';
+    relation: string;
+    quantifier?: {
+        kind: 'ANY' | 'ALL' | 'COUNT';
+        op?: 'GT' | 'GTE' | 'EQ' | 'LT' | 'LTE';
+        value?: number;
+    };
+    exposeAs?: string;
+    outcome: EvaluationOutcomeEnum;
+    matched: number;
+    errored: number;
+    total: number;
+    related: TraceRelatedResponse[];
+    /** Solo si `outcome` es `ERROR` (`RELATION_NOT_RESOLVED`, `RELATED_UNDECIDABLE`, `MAX_RELATED_EXCEEDED`…). */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
 export declare class TraceGroupResponse {
     match: 'ALL' | 'ANY';
     outcome: EvaluationOutcomeEnum;
-    conditions: TraceConditionResponse[];
+    conditions: (TraceConditionResponse | TraceRelationResponse)[];
 }
 /** Traza completa de una evaluación: por qué cumplió o no (criterio de éxito 4). */
 export declare class ResultTraceResponse {

package/bin/rewardsEligibility/dtos/backoffice/ResultTraceResponse.js

@@ -1,10 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ResultTraceResponse = exports.TraceGroupResponse = exports.TraceConditionResponse = void 0;
+exports.ResultTraceResponse = exports.TraceGroupResponse = exports.TraceRelationResponse = exports.TraceRelatedResponse = exports.TraceConditionResponse = void 0;
 /** Una condición evaluada: qué se esperaba, qué se encontró y de dónde salió el dato (spec 5.4). */
 class TraceConditionResponse {
 }
 exports.TraceConditionResponse = TraceConditionResponse;
+/** Un relacionado evaluado dentro de un bloque de relación, con su traza propia. */
+class TraceRelatedResponse {
+}
+exports.TraceRelatedResponse = TraceRelatedResponse;
+/** Un bloque de relación evaluado (ej. «referidos»). Discriminante: `kind: 'RELATION'`. Sin `origin`/`asOf`. */
+class TraceRelationResponse {
+}
+exports.TraceRelationResponse = TraceRelationResponse;
 class TraceGroupResponse {
 }
 exports.TraceGroupResponse = TraceGroupResponse;

package/bin/rewardsEligibility/dtos/backoffice/RuleCatalogResponse.d.ts

@@ -1,4 +1,6 @@
 import { InputField } from '../../../dynamicForm/dtos/InputField';
+import { RulesRelationCardinalityEnum } from '../../../rules/enums/RulesRelationCardinalityEnum';
+import { RulesRelationTargetEnum } from '../../../rules/enums/RulesRelationTargetEnum';
 import { RuleValueTypeEnum } from '../../enums/RuleValueTypeEnum';
 /** Un campo que una fuente resuelve para las reglas (`GET /rule-catalog`). */
 export declare class RuleCatalogFieldResponse {
@@ -26,8 +28,22 @@ export declare class RuleCatalogSourceResponse {
     description: string;
     fields: RuleCatalogFieldResponse[];
 }
+/** Una relación que las reglas pueden recorrer (espejo de `RulesCatalogRelationResponse`). */
+export declare class RuleCatalogRelationResponse {
+    name: string;
+    label: string;
+    description: string;
+    cardinality: RulesRelationCardinalityEnum;
+    target: RulesRelationTargetEnum;
+    /** Solo LIVE: tope de relacionados por sujeto; excederlo da ERROR, nunca trunca. */
+    maxRelated?: number;
+    /** Solo target RECORD: campos propios del registro. */
+    fields?: RuleCatalogFieldResponse[];
+}
 export declare class RuleCatalogResponse {
     sources: RuleCatalogSourceResponse[];
     /** Etiqueta legible de cada operador (`GTE` → «≥»). */
     operators: Record<string, string>;
+    /** Relaciones disponibles (vacío si no hay). */
+    relations: RuleCatalogRelationResponse[];
 }

package/bin/rewardsEligibility/dtos/backoffice/RuleCatalogResponse.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RuleCatalogResponse = exports.RuleCatalogSourceResponse = exports.RuleCatalogFieldResponse = void 0;
+exports.RuleCatalogResponse = exports.RuleCatalogRelationResponse = exports.RuleCatalogSourceResponse = exports.RuleCatalogFieldResponse = void 0;
 /** Un campo que una fuente resuelve para las reglas (`GET /rule-catalog`). */
 class RuleCatalogFieldResponse {
 }
@@ -8,6 +8,10 @@ exports.RuleCatalogFieldResponse = RuleCatalogFieldResponse;
 class RuleCatalogSourceResponse {
 }
 exports.RuleCatalogSourceResponse = RuleCatalogSourceResponse;
+/** Una relación que las reglas pueden recorrer (espejo de `RulesCatalogRelationResponse`). */
+class RuleCatalogRelationResponse {
+}
+exports.RuleCatalogRelationResponse = RuleCatalogRelationResponse;
 class RuleCatalogResponse {
 }
 exports.RuleCatalogResponse = RuleCatalogResponse;

package/bin/rewardsEligibility/enums/RulesRelationCardinalityEnum.d.ts

@@ -0,0 +1 @@
+export * from '../../rules/enums/RulesRelationCardinalityEnum';

package/bin/rewardsEligibility/enums/RulesRelationCardinalityEnum.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("../../rules/enums/RulesRelationCardinalityEnum"), exports);

package/bin/rewardsEligibility/enums/RulesRelationTargetEnum.d.ts

@@ -0,0 +1 @@
+export * from '../../rules/enums/RulesRelationTargetEnum';

package/bin/rewardsEligibility/enums/RulesRelationTargetEnum.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("../../rules/enums/RulesRelationTargetEnum"), exports);

package/bin/rewardsEligibility/index.d.ts

@@ -30,6 +30,8 @@ export * from './dtos/EvaluationReward';
 export * from './dtos/EvaluationTrigger';
 export * from './enums/MetricsDimensionEnum';
 export * from './enums/RuleValueTypeEnum';
+export * from './enums/RulesRelationCardinalityEnum';
+export * from './enums/RulesRelationTargetEnum';
 export * from './enums/RulesChatRoleEnum';
 export * from './constants/BackofficeLimits';
 export * from './constants/BatchLimits';

package/bin/rewardsEligibility/index.js

@@ -52,6 +52,8 @@ __exportStar(require("./dtos/EvaluationTrigger"), exports);
 //Backoffice (fase 3): enums, constantes y DTOs
 __exportStar(require("./enums/MetricsDimensionEnum"), exports);
 __exportStar(require("./enums/RuleValueTypeEnum"), exports);
+__exportStar(require("./enums/RulesRelationCardinalityEnum"), exports);
+__exportStar(require("./enums/RulesRelationTargetEnum"), exports);
 __exportStar(require("./enums/RulesChatRoleEnum"), exports);
 __exportStar(require("./constants/BackofficeLimits"), exports);
 __exportStar(require("./constants/BatchLimits"), exports);

package/bin/rules/constants/RulesRelationLimits.d.ts

@@ -0,0 +1,15 @@
+/** Nombre de relación del catálogo (`referidos`, `referidor`). */
+export declare const RULES_RELATION_NAME_PATTERN: RegExp;
+/** Nombre con el que un bloque de relación expone su conteo como campo devuelto. */
+export declare const RULES_EXPOSE_AS_PATTERN: RegExp;
+/** Profundidad máxima de anidación de bloques de relación. */
+export declare const RULES_MAX_RELATION_DEPTH = 2;
+/** Máximo de bloques de relación por regla (todos los niveles). */
+export declare const RULES_MAX_RELATION_BLOCKS = 5;
+/** Máximo de días del operador `WITHIN_LAST_DAYS`. */
+export declare const RULES_MAX_WITHIN_LAST_DAYS = 365;
+/**
+ * Id del campo devuelto que expone un bloque de relación: `relación:exposeAs`
+ * (ej. `referidos:referidos_mx_count`). Cumple `RETURN_FIELD_ID_PATTERN`.
+ */
+export declare function relationReturnFieldId(relation: string, exposeAs: string): string;

package/bin/rules/constants/RulesRelationLimits.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RULES_MAX_WITHIN_LAST_DAYS = exports.RULES_MAX_RELATION_BLOCKS = exports.RULES_MAX_RELATION_DEPTH = exports.RULES_EXPOSE_AS_PATTERN = exports.RULES_RELATION_NAME_PATTERN = void 0;
+exports.relationReturnFieldId = relationReturnFieldId;
+/** Nombre de relación del catálogo (`referidos`, `referidor`). */
+exports.RULES_RELATION_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Nombre con el que un bloque de relación expone su conteo como campo devuelto. */
+exports.RULES_EXPOSE_AS_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+/** Profundidad máxima de anidación de bloques de relación. */
+exports.RULES_MAX_RELATION_DEPTH = 2;
+/** Máximo de bloques de relación por regla (todos los niveles). */
+exports.RULES_MAX_RELATION_BLOCKS = 5;
+/** Máximo de días del operador `WITHIN_LAST_DAYS`. */
+exports.RULES_MAX_WITHIN_LAST_DAYS = 365;
+/**
+ * Id del campo devuelto que expone un bloque de relación: `relación:exposeAs`
+ * (ej. `referidos:referidos_mx_count`). Cumple `RETURN_FIELD_ID_PATTERN`.
+ */
+function relationReturnFieldId(relation, exposeAs) {
+    return `${relation}:${exposeAs}`;
+}

package/bin/rules/dtos/RulesCatalogResponse.d.ts

@@ -1,4 +1,6 @@
 import { InputField } from '../../dynamicForm/dtos/InputField';
+import { RulesRelationCardinalityEnum } from '../enums/RulesRelationCardinalityEnum';
+import { RulesRelationTargetEnum } from '../enums/RulesRelationTargetEnum';
 import { RulesValueTypeEnum } from '../enums/RulesValueTypeEnum';
 /** Un campo que un ítem del catálogo resuelve para las reglas. */
 export declare class RulesCatalogFieldResponse {
@@ -29,8 +31,22 @@ export declare class RulesCatalogItemResponse {
     description: string;
     fields: RulesCatalogFieldResponse[];
 }
+/** Una relación que las reglas pueden recorrer (ej. `referidos`): bloque `RELATION` con sub-regla. */
+export declare class RulesCatalogRelationResponse {
+    name: string;
+    label: string;
+    description: string;
+    cardinality: RulesRelationCardinalityEnum;
+    target: RulesRelationTargetEnum;
+    /** Solo LIVE: tope de relacionados por sujeto; excederlo da ERROR, nunca trunca. */
+    maxRelated?: number;
+    /** Solo target RECORD: campos propios del registro. */
+    fields?: RulesCatalogFieldResponse[];
+}
 export declare class RulesCatalogResponse {
     items: RulesCatalogItemResponse[];
     /** Etiqueta legible de cada operador (`GTE` → «≥»). */
     operators: Record<string, string>;
+    /** Relaciones disponibles (vacío si no hay). */
+    relations: RulesCatalogRelationResponse[];
 }

package/bin/rules/dtos/RulesCatalogResponse.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RulesCatalogResponse = exports.RulesCatalogItemResponse = exports.RulesCatalogFieldResponse = void 0;
+exports.RulesCatalogResponse = exports.RulesCatalogRelationResponse = exports.RulesCatalogItemResponse = exports.RulesCatalogFieldResponse = void 0;
 /** Un campo que un ítem del catálogo resuelve para las reglas. */
 class RulesCatalogFieldResponse {
 }
@@ -9,6 +9,10 @@ exports.RulesCatalogFieldResponse = RulesCatalogFieldResponse;
 class RulesCatalogItemResponse {
 }
 exports.RulesCatalogItemResponse = RulesCatalogItemResponse;
+/** Una relación que las reglas pueden recorrer (ej. `referidos`): bloque `RELATION` con sub-regla. */
+class RulesCatalogRelationResponse {
+}
+exports.RulesCatalogRelationResponse = RulesCatalogRelationResponse;
 class RulesCatalogResponse {
 }
 exports.RulesCatalogResponse = RulesCatalogResponse;

package/bin/rules/dtos/RulesTraceResponse.d.ts

@@ -19,10 +19,43 @@ export declare class RulesTraceConditionResponse {
         message: string;
     };
 }
+/** Un relacionado evaluado dentro de un bloque de relación, con su traza propia. */
+export declare class RulesTraceRelatedResponse {
+    directoryId: string;
+    outcome: RulesOutcomeEnum;
+    trace: RulesTraceResponse;
+}
+/**
+ * Un bloque de relación evaluado (ej. «referidos»). Discriminante: `kind: 'RELATION'`.
+ * No lleva `origin`/`asOf`; los relacionados pueden llevarlos en su `trace` anidado.
+ */
+export declare class RulesTraceRelationResponse {
+    kind: 'RELATION';
+    relation: string;
+    quantifier?: {
+        kind: 'ANY' | 'ALL' | 'COUNT';
+        op?: 'GT' | 'GTE' | 'EQ' | 'LT' | 'LTE';
+        value?: number;
+    };
+    exposeAs?: string;
+    outcome: RulesOutcomeEnum;
+    matched: number;
+    errored: number;
+    total: number;
+    related: RulesTraceRelatedResponse[];
+    /**
+     * Solo si `outcome` es `ERROR`. `code` ∈ `RELATION_NOT_RESOLVED`, `RELATED_UNDECIDABLE`,
+     * `RELATION_CARDINALITY_VIOLATION`, `MAX_DEPTH_EXCEEDED` o el código del resolver (`MAX_RELATED_EXCEEDED`, `RESOLVER_FAILED`…).
+     */
+    error?: {
+        code: string;
+        message: string;
+    };
+}
 export declare class RulesTraceGroupResponse {
     match: 'ALL' | 'ANY';
     outcome: RulesOutcomeEnum;
-    conditions: RulesTraceConditionResponse[];
+    conditions: (RulesTraceConditionResponse | RulesTraceRelationResponse)[];
 }
 /** Traza completa de una evaluación: por qué cumplió o no. */
 export declare class RulesTraceResponse {

package/bin/rules/dtos/RulesTraceResponse.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RulesTraceResponse = exports.RulesTraceGroupResponse = exports.RulesTraceConditionResponse = void 0;
+exports.RulesTraceResponse = exports.RulesTraceGroupResponse = exports.RulesTraceRelationResponse = exports.RulesTraceRelatedResponse = exports.RulesTraceConditionResponse = void 0;
 /**
  * Una condición evaluada: qué se esperaba y qué se encontró.
  * Sin `origin`/`asOf`: el central no sabe de dónde salió el dato; el consumidor (rewards) los agrega.
@@ -8,6 +8,17 @@ exports.RulesTraceResponse = exports.RulesTraceGroupResponse = exports.RulesTrac
 class RulesTraceConditionResponse {
 }
 exports.RulesTraceConditionResponse = RulesTraceConditionResponse;
+/** Un relacionado evaluado dentro de un bloque de relación, con su traza propia. */
+class RulesTraceRelatedResponse {
+}
+exports.RulesTraceRelatedResponse = RulesTraceRelatedResponse;
+/**
+ * Un bloque de relación evaluado (ej. «referidos»). Discriminante: `kind: 'RELATION'`.
+ * No lleva `origin`/`asOf`; los relacionados pueden llevarlos en su `trace` anidado.
+ */
+class RulesTraceRelationResponse {
+}
+exports.RulesTraceRelationResponse = RulesTraceRelationResponse;
 class RulesTraceGroupResponse {
 }
 exports.RulesTraceGroupResponse = RulesTraceGroupResponse;

package/bin/rules/dtos/ValidateRulesResponse.d.ts

@@ -1,6 +1,28 @@
+import { RulesNodeErrorCodeEnum } from '../enums/RulesNodeErrorCodeEnum';
+import { RulesValueTypeEnum } from '../enums/RulesValueTypeEnum';
+/** Error de validación de un nodo del árbol de la regla (bloque de relación o condición). */
+export declare class RulesNodeValidationErrorResponse {
+    /** Ruta del nodo dentro de la regla (para pintar el error en el editor). */
+    path: string;
+    code: RulesNodeErrorCodeEnum;
+    message: string;
+}
+/** Campo devuelto que expone un bloque de relación con `exposeAs`. */
+export declare class RulesExposedFieldResponse {
+    /** `relación:exposeAs` (ver `relationReturnFieldId`); cumple `RETURN_FIELD_ID_PATTERN`. */
+    id: string;
+    relation: string;
+    exposeAs: string;
+    /** Siempre `NUMBER` (conteo de relacionados). */
+    valueType: RulesValueTypeEnum;
+}
 /** Resultado de `POST /validate`. */
 export declare class ValidateRulesResponse {
     valid: boolean;
     /** Mensajes de `validateRule`, tal cual (vacío si `valid`). */
     errors: string[];
+    /** Errores por nodo de relación (vacío si no hay). */
+    nodeErrors: RulesNodeValidationErrorResponse[];
+    /** Campos que la regla puede devolver vía `exposeAs` (vacío si no hay). */
+    exposedFields: RulesExposedFieldResponse[];
 }

package/bin/rules/dtos/ValidateRulesResponse.js

@@ -1,6 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ValidateRulesResponse = void 0;
+exports.ValidateRulesResponse = exports.RulesExposedFieldResponse = exports.RulesNodeValidationErrorResponse = void 0;
+/** Error de validación de un nodo del árbol de la regla (bloque de relación o condición). */
+class RulesNodeValidationErrorResponse {
+}
+exports.RulesNodeValidationErrorResponse = RulesNodeValidationErrorResponse;
+/** Campo devuelto que expone un bloque de relación con `exposeAs`. */
+class RulesExposedFieldResponse {
+}
+exports.RulesExposedFieldResponse = RulesExposedFieldResponse;
 /** Resultado de `POST /validate`. */
 class ValidateRulesResponse {
 }

package/bin/rules/enums/RulesNodeErrorCodeEnum.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Códigos de error de validación de nodos de relación en `POST /validate`.
+ * Mismos strings que `RelationIssueCode` de `@fiado/rules-engine`.
+ */
+export declare enum RulesNodeErrorCodeEnum {
+    UNKNOWN_RELATION = "UNKNOWN_RELATION",
+    INVALID_RELATION_NODE = "INVALID_RELATION_NODE",
+    QUANTIFIER_REQUIRED = "QUANTIFIER_REQUIRED",
+    QUANTIFIER_NOT_ALLOWED = "QUANTIFIER_NOT_ALLOWED",
+    INVALID_QUANTIFIER = "INVALID_QUANTIFIER",
+    SUBJECT_IN_RELATION = "SUBJECT_IN_RELATION",
+    EXPOSE_AS_NOT_ALLOWED = "EXPOSE_AS_NOT_ALLOWED",
+    INVALID_EXPOSE_AS = "INVALID_EXPOSE_AS",
+    DUPLICATE_EXPOSE_AS = "DUPLICATE_EXPOSE_AS",
+    MAX_DEPTH_EXCEEDED = "MAX_DEPTH_EXCEEDED",
+    MAX_BLOCKS_EXCEEDED = "MAX_BLOCKS_EXCEEDED",
+    /** LIVE rechaza una sub-regla 1:N con fuentes que no consultan por lote. */
+    RELATION_SOURCE_NOT_BATCH_CAPABLE = "RELATION_SOURCE_NOT_BATCH_CAPABLE",
+    /** Runtime: un sujeto excede `maxRelated`. */
+    MAX_RELATED_EXCEEDED = "MAX_RELATED_EXCEEDED"
+}

package/bin/rules/enums/RulesNodeErrorCodeEnum.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RulesNodeErrorCodeEnum = void 0;
+/**
+ * Códigos de error de validación de nodos de relación en `POST /validate`.
+ * Mismos strings que `RelationIssueCode` de `@fiado/rules-engine`.
+ */
+var RulesNodeErrorCodeEnum;
+(function (RulesNodeErrorCodeEnum) {
+    RulesNodeErrorCodeEnum["UNKNOWN_RELATION"] = "UNKNOWN_RELATION";
+    RulesNodeErrorCodeEnum["INVALID_RELATION_NODE"] = "INVALID_RELATION_NODE";
+    RulesNodeErrorCodeEnum["QUANTIFIER_REQUIRED"] = "QUANTIFIER_REQUIRED";
+    RulesNodeErrorCodeEnum["QUANTIFIER_NOT_ALLOWED"] = "QUANTIFIER_NOT_ALLOWED";
+    RulesNodeErrorCodeEnum["INVALID_QUANTIFIER"] = "INVALID_QUANTIFIER";
+    RulesNodeErrorCodeEnum["SUBJECT_IN_RELATION"] = "SUBJECT_IN_RELATION";
+    RulesNodeErrorCodeEnum["EXPOSE_AS_NOT_ALLOWED"] = "EXPOSE_AS_NOT_ALLOWED";
+    RulesNodeErrorCodeEnum["INVALID_EXPOSE_AS"] = "INVALID_EXPOSE_AS";
+    RulesNodeErrorCodeEnum["DUPLICATE_EXPOSE_AS"] = "DUPLICATE_EXPOSE_AS";
+    RulesNodeErrorCodeEnum["MAX_DEPTH_EXCEEDED"] = "MAX_DEPTH_EXCEEDED";
+    RulesNodeErrorCodeEnum["MAX_BLOCKS_EXCEEDED"] = "MAX_BLOCKS_EXCEEDED";
+    /** LIVE rechaza una sub-regla 1:N con fuentes que no consultan por lote. */
+    RulesNodeErrorCodeEnum["RELATION_SOURCE_NOT_BATCH_CAPABLE"] = "RELATION_SOURCE_NOT_BATCH_CAPABLE";
+    /** Runtime: un sujeto excede `maxRelated`. */
+    RulesNodeErrorCodeEnum["MAX_RELATED_EXCEEDED"] = "MAX_RELATED_EXCEEDED";
+})(RulesNodeErrorCodeEnum || (exports.RulesNodeErrorCodeEnum = RulesNodeErrorCodeEnum = {}));

package/bin/rules/enums/RulesRelationCardinalityEnum.d.ts

@@ -0,0 +1,5 @@
+/** Cardinalidad de una relación del catálogo de reglas: un relacionado (1:1) o varios (1:N). */
+export declare enum RulesRelationCardinalityEnum {
+    ONE = "ONE",
+    MANY = "MANY"
+}

package/bin/rules/enums/RulesRelationCardinalityEnum.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RulesRelationCardinalityEnum = void 0;
+/** Cardinalidad de una relación del catálogo de reglas: un relacionado (1:1) o varios (1:N). */
+var RulesRelationCardinalityEnum;
+(function (RulesRelationCardinalityEnum) {
+    RulesRelationCardinalityEnum["ONE"] = "ONE";
+    RulesRelationCardinalityEnum["MANY"] = "MANY";
+})(RulesRelationCardinalityEnum || (exports.RulesRelationCardinalityEnum = RulesRelationCardinalityEnum = {}));

package/bin/rules/enums/RulesRelationTargetEnum.d.ts

@@ -0,0 +1,5 @@
+/** A qué apunta una relación: otra persona (`PERSON`) o registros propios con campos (`RECORD`, ej. créditos). */
+export declare enum RulesRelationTargetEnum {
+    PERSON = "PERSON",
+    RECORD = "RECORD"
+}

package/bin/rules/enums/RulesRelationTargetEnum.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RulesRelationTargetEnum = void 0;
+/** A qué apunta una relación: otra persona (`PERSON`) o registros propios con campos (`RECORD`, ej. créditos). */
+var RulesRelationTargetEnum;
+(function (RulesRelationTargetEnum) {
+    RulesRelationTargetEnum["PERSON"] = "PERSON";
+    RulesRelationTargetEnum["RECORD"] = "RECORD";
+})(RulesRelationTargetEnum || (exports.RulesRelationTargetEnum = RulesRelationTargetEnum = {}));

package/bin/rules/index.d.ts

@@ -3,7 +3,11 @@ export * from './enums/RulesGenerationStatusEnum';
 export * from './enums/RulesChatRoleEnum';
 export * from './enums/RulesValueTypeEnum';
 export * from './enums/RulesErrorCodeEnum';
+export * from './enums/RulesRelationCardinalityEnum';
+export * from './enums/RulesRelationTargetEnum';
+export * from './enums/RulesNodeErrorCodeEnum';
 export * from './constants/RulesLimits';
+export * from './constants/RulesRelationLimits';
 export * from './dtos/RulesCatalogResponse';
 export * from './dtos/ValidateRulesRequest';
 export * from './dtos/ValidateRulesResponse';

package/bin/rules/index.js

@@ -20,8 +20,12 @@ __exportStar(require("./enums/RulesGenerationStatusEnum"), exports);
 __exportStar(require("./enums/RulesChatRoleEnum"), exports);
 __exportStar(require("./enums/RulesValueTypeEnum"), exports);
 __exportStar(require("./enums/RulesErrorCodeEnum"), exports);
+__exportStar(require("./enums/RulesRelationCardinalityEnum"), exports);
+__exportStar(require("./enums/RulesRelationTargetEnum"), exports);
+__exportStar(require("./enums/RulesNodeErrorCodeEnum"), exports);
 //Constants
 __exportStar(require("./constants/RulesLimits"), exports);
+__exportStar(require("./constants/RulesRelationLimits"), exports);
 //DTOs
 __exportStar(require("./dtos/RulesCatalogResponse"), exports);
 __exportStar(require("./dtos/ValidateRulesRequest"), exports);

package/package.json

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

package/src/directory/index.ts

@@ -11,8 +11,6 @@ export * from './dtos/DeleteByDirectoryResponse';
 export * from './dtos/DirectoryAgentsBySponsorRequest';
 export * from './dtos/DirectoryAgentsBySponsorResponse';
 export * from './dtos/DirectoryUserScopeUpdateRequest';
-export * from './dtos/AccountCreatedEventDetail';
-
 export * from './dtos/External';
 
 
@@ -20,3 +18,6 @@ export * from './dtos/External';
 export * from './enums/TypeOfDirectoryId';
 export * from './enums/DirectoryBackofficeStatusEnum';
 export * from './enums/DirectoryUserLifecycleEventTypeEnum';
+
+//events
+export * from './events/AccountCreatedEventDetail';

package/src/rewardsEligibility/dtos/backoffice/ResultTraceResponse.ts

@@ -20,10 +20,32 @@ export class TraceConditionResponse {
     error?: { code: string; message: string };
 }
 
+/** Un relacionado evaluado dentro de un bloque de relación, con su traza propia. */
+export class TraceRelatedResponse {
+    directoryId: string;
+    outcome: EvaluationOutcomeEnum;
+    trace: ResultTraceResponse;
+}
+
+/** Un bloque de relación evaluado (ej. «referidos»). Discriminante: `kind: 'RELATION'`. Sin `origin`/`asOf`. */
+export class TraceRelationResponse {
+    kind: 'RELATION';
+    relation: string;
+    quantifier?: { kind: 'ANY' | 'ALL' | 'COUNT'; op?: 'GT' | 'GTE' | 'EQ' | 'LT' | 'LTE'; value?: number };
+    exposeAs?: string;
+    outcome: EvaluationOutcomeEnum;
+    matched: number;
+    errored: number;
+    total: number;
+    related: TraceRelatedResponse[];
+    /** Solo si `outcome` es `ERROR` (`RELATION_NOT_RESOLVED`, `RELATED_UNDECIDABLE`, `MAX_RELATED_EXCEEDED`…). */
+    error?: { code: string; message: string };
+}
+
 export class TraceGroupResponse {
     match: 'ALL' | 'ANY';
     outcome: EvaluationOutcomeEnum;
-    conditions: TraceConditionResponse[];
+    conditions: (TraceConditionResponse | TraceRelationResponse)[];
 }
 
 /** Traza completa de una evaluación: por qué cumplió o no (criterio de éxito 4). */

package/src/rewardsEligibility/dtos/backoffice/RuleCatalogResponse.ts

@@ -1,4 +1,6 @@
 import { InputField } from '../../../dynamicForm/dtos/InputField';
+import { RulesRelationCardinalityEnum } from '../../../rules/enums/RulesRelationCardinalityEnum';
+import { RulesRelationTargetEnum } from '../../../rules/enums/RulesRelationTargetEnum';
 import { RuleValueTypeEnum } from '../../enums/RuleValueTypeEnum';
 
 /** Un campo que una fuente resuelve para las reglas (`GET /rule-catalog`). */
@@ -25,8 +27,23 @@ export class RuleCatalogSourceResponse {
     fields: RuleCatalogFieldResponse[];
 }
 
+/** Una relación que las reglas pueden recorrer (espejo de `RulesCatalogRelationResponse`). */
+export class RuleCatalogRelationResponse {
+    name: string;
+    label: string;
+    description: string;
+    cardinality: RulesRelationCardinalityEnum;
+    target: RulesRelationTargetEnum;
+    /** Solo LIVE: tope de relacionados por sujeto; excederlo da ERROR, nunca trunca. */
+    maxRelated?: number;
+    /** Solo target RECORD: campos propios del registro. */
+    fields?: RuleCatalogFieldResponse[];
+}
+
 export class RuleCatalogResponse {
     sources: RuleCatalogSourceResponse[];
     /** Etiqueta legible de cada operador (`GTE` → «≥»). */
     operators: Record<string, string>;
+    /** Relaciones disponibles (vacío si no hay). */
+    relations: RuleCatalogRelationResponse[];
 }

package/src/rewardsEligibility/enums/RulesRelationCardinalityEnum.ts

@@ -0,0 +1 @@
+export * from '../../rules/enums/RulesRelationCardinalityEnum';

package/src/rewardsEligibility/enums/RulesRelationTargetEnum.ts

@@ -0,0 +1 @@
+export * from '../../rules/enums/RulesRelationTargetEnum';

package/src/rewardsEligibility/index.ts

@@ -41,6 +41,8 @@ export * from './dtos/EvaluationTrigger';
 //Backoffice (fase 3): enums, constantes y DTOs
 export * from './enums/MetricsDimensionEnum';
 export * from './enums/RuleValueTypeEnum';
+export * from './enums/RulesRelationCardinalityEnum';
+export * from './enums/RulesRelationTargetEnum';
 export * from './enums/RulesChatRoleEnum';
 export * from './constants/BackofficeLimits';
 export * from './constants/BatchLimits';

package/src/rules/constants/RulesRelationLimits.ts

@@ -0,0 +1,18 @@
+/** Nombre de relación del catálogo (`referidos`, `referidor`). */
+export const RULES_RELATION_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+/** Nombre con el que un bloque de relación expone su conteo como campo devuelto. */
+export const RULES_EXPOSE_AS_PATTERN = /^[A-Za-z][A-Za-z0-9_]*$/;
+/** Profundidad máxima de anidación de bloques de relación. */
+export const RULES_MAX_RELATION_DEPTH = 2;
+/** Máximo de bloques de relación por regla (todos los niveles). */
+export const RULES_MAX_RELATION_BLOCKS = 5;
+/** Máximo de días del operador `WITHIN_LAST_DAYS`. */
+export const RULES_MAX_WITHIN_LAST_DAYS = 365;
+
+/**
+ * Id del campo devuelto que expone un bloque de relación: `relación:exposeAs`
+ * (ej. `referidos:referidos_mx_count`). Cumple `RETURN_FIELD_ID_PATTERN`.
+ */
+export function relationReturnFieldId(relation: string, exposeAs: string): string {
+    return `${relation}:${exposeAs}`;
+}

package/src/rules/dtos/RulesCatalogResponse.ts

@@ -1,4 +1,6 @@
 import { InputField } from '../../dynamicForm/dtos/InputField';
+import { RulesRelationCardinalityEnum } from '../enums/RulesRelationCardinalityEnum';
+import { RulesRelationTargetEnum } from '../enums/RulesRelationTargetEnum';
 import { RulesValueTypeEnum } from '../enums/RulesValueTypeEnum';
 
 /** Un campo que un ítem del catálogo resuelve para las reglas. */
@@ -28,8 +30,23 @@ export class RulesCatalogItemResponse {
     fields: RulesCatalogFieldResponse[];
 }
 
+/** Una relación que las reglas pueden recorrer (ej. `referidos`): bloque `RELATION` con sub-regla. */
+export class RulesCatalogRelationResponse {
+    name: string;
+    label: string;
+    description: string;
+    cardinality: RulesRelationCardinalityEnum;
+    target: RulesRelationTargetEnum;
+    /** Solo LIVE: tope de relacionados por sujeto; excederlo da ERROR, nunca trunca. */
+    maxRelated?: number;
+    /** Solo target RECORD: campos propios del registro. */
+    fields?: RulesCatalogFieldResponse[];
+}
+
 export class RulesCatalogResponse {
     items: RulesCatalogItemResponse[];
     /** Etiqueta legible de cada operador (`GTE` → «≥»). */
     operators: Record<string, string>;
+    /** Relaciones disponibles (vacío si no hay). */
+    relations: RulesCatalogRelationResponse[];
 }

package/src/rules/dtos/RulesTraceResponse.ts

@@ -18,10 +18,38 @@ export class RulesTraceConditionResponse {
     error?: { code: string; message: string };
 }
 
+/** Un relacionado evaluado dentro de un bloque de relación, con su traza propia. */
+export class RulesTraceRelatedResponse {
+    directoryId: string;
+    outcome: RulesOutcomeEnum;
+    trace: RulesTraceResponse;
+}
+
+/**
+ * Un bloque de relación evaluado (ej. «referidos»). Discriminante: `kind: 'RELATION'`.
+ * No lleva `origin`/`asOf`; los relacionados pueden llevarlos en su `trace` anidado.
+ */
+export class RulesTraceRelationResponse {
+    kind: 'RELATION';
+    relation: string;
+    quantifier?: { kind: 'ANY' | 'ALL' | 'COUNT'; op?: 'GT' | 'GTE' | 'EQ' | 'LT' | 'LTE'; value?: number };
+    exposeAs?: string;
+    outcome: RulesOutcomeEnum;
+    matched: number;
+    errored: number;
+    total: number;
+    related: RulesTraceRelatedResponse[];
+    /**
+     * Solo si `outcome` es `ERROR`. `code` ∈ `RELATION_NOT_RESOLVED`, `RELATED_UNDECIDABLE`,
+     * `RELATION_CARDINALITY_VIOLATION`, `MAX_DEPTH_EXCEEDED` o el código del resolver (`MAX_RELATED_EXCEEDED`, `RESOLVER_FAILED`…).
+     */
+    error?: { code: string; message: string };
+}
+
 export class RulesTraceGroupResponse {
     match: 'ALL' | 'ANY';
     outcome: RulesOutcomeEnum;
-    conditions: RulesTraceConditionResponse[];
+    conditions: (RulesTraceConditionResponse | RulesTraceRelationResponse)[];
 }
 
 /** Traza completa de una evaluación: por qué cumplió o no. */

package/src/rules/dtos/ValidateRulesResponse.ts

@@ -1,6 +1,31 @@
+import { RulesNodeErrorCodeEnum } from '../enums/RulesNodeErrorCodeEnum';
+import { RulesValueTypeEnum } from '../enums/RulesValueTypeEnum';
+
+/** Error de validación de un nodo del árbol de la regla (bloque de relación o condición). */
+export class RulesNodeValidationErrorResponse {
+    /** Ruta del nodo dentro de la regla (para pintar el error en el editor). */
+    path: string;
+    code: RulesNodeErrorCodeEnum;
+    message: string;
+}
+
+/** Campo devuelto que expone un bloque de relación con `exposeAs`. */
+export class RulesExposedFieldResponse {
+    /** `relación:exposeAs` (ver `relationReturnFieldId`); cumple `RETURN_FIELD_ID_PATTERN`. */
+    id: string;
+    relation: string;
+    exposeAs: string;
+    /** Siempre `NUMBER` (conteo de relacionados). */
+    valueType: RulesValueTypeEnum;
+}
+
 /** Resultado de `POST /validate`. */
 export class ValidateRulesResponse {
     valid: boolean;
     /** Mensajes de `validateRule`, tal cual (vacío si `valid`). */
     errors: string[];
+    /** Errores por nodo de relación (vacío si no hay). */
+    nodeErrors: RulesNodeValidationErrorResponse[];
+    /** Campos que la regla puede devolver vía `exposeAs` (vacío si no hay). */
+    exposedFields: RulesExposedFieldResponse[];
 }

package/src/rules/enums/RulesNodeErrorCodeEnum.ts

@@ -0,0 +1,21 @@
+/**
+ * Códigos de error de validación de nodos de relación en `POST /validate`.
+ * Mismos strings que `RelationIssueCode` de `@fiado/rules-engine`.
+ */
+export enum RulesNodeErrorCodeEnum {
+    UNKNOWN_RELATION = 'UNKNOWN_RELATION',
+    INVALID_RELATION_NODE = 'INVALID_RELATION_NODE',
+    QUANTIFIER_REQUIRED = 'QUANTIFIER_REQUIRED',
+    QUANTIFIER_NOT_ALLOWED = 'QUANTIFIER_NOT_ALLOWED',
+    INVALID_QUANTIFIER = 'INVALID_QUANTIFIER',
+    SUBJECT_IN_RELATION = 'SUBJECT_IN_RELATION',
+    EXPOSE_AS_NOT_ALLOWED = 'EXPOSE_AS_NOT_ALLOWED',
+    INVALID_EXPOSE_AS = 'INVALID_EXPOSE_AS',
+    DUPLICATE_EXPOSE_AS = 'DUPLICATE_EXPOSE_AS',
+    MAX_DEPTH_EXCEEDED = 'MAX_DEPTH_EXCEEDED',
+    MAX_BLOCKS_EXCEEDED = 'MAX_BLOCKS_EXCEEDED',
+    /** LIVE rechaza una sub-regla 1:N con fuentes que no consultan por lote. */
+    RELATION_SOURCE_NOT_BATCH_CAPABLE = 'RELATION_SOURCE_NOT_BATCH_CAPABLE',
+    /** Runtime: un sujeto excede `maxRelated`. */
+    MAX_RELATED_EXCEEDED = 'MAX_RELATED_EXCEEDED',
+}

package/src/rules/enums/RulesRelationCardinalityEnum.ts

@@ -0,0 +1,5 @@
+/** Cardinalidad de una relación del catálogo de reglas: un relacionado (1:1) o varios (1:N). */
+export enum RulesRelationCardinalityEnum {
+    ONE = 'ONE',
+    MANY = 'MANY',
+}

package/src/rules/enums/RulesRelationTargetEnum.ts

@@ -0,0 +1,5 @@
+/** A qué apunta una relación: otra persona (`PERSON`) o registros propios con campos (`RECORD`, ej. créditos). */
+export enum RulesRelationTargetEnum {
+    PERSON = 'PERSON',
+    RECORD = 'RECORD',
+}

package/src/rules/index.ts

@@ -4,9 +4,13 @@ export * from './enums/RulesGenerationStatusEnum';
 export * from './enums/RulesChatRoleEnum';
 export * from './enums/RulesValueTypeEnum';
 export * from './enums/RulesErrorCodeEnum';
+export * from './enums/RulesRelationCardinalityEnum';
+export * from './enums/RulesRelationTargetEnum';
+export * from './enums/RulesNodeErrorCodeEnum';
 
 //Constants
 export * from './constants/RulesLimits';
+export * from './constants/RulesRelationLimits';
 
 //DTOs
 export * from './dtos/RulesCatalogResponse';