@fiado/type-kit 3.491.0 → 3.492.0

package/_test_/unit/loanCredit/installmentPaidEvent.test.ts

@@ -0,0 +1,17 @@
+import 'reflect-metadata';
+import * as LoanCredit from '../../../src/loanCredit';
+
+describe('loanCredit — cuota pagada', () => {
+    it('el evento lleva la cuota, lo pagado y el instante del pago', () => {
+        const payload: LoanCredit.InstallmentPaidV1Payload = {
+            creditId: 'CR-1',
+            installmentNumber: 3,
+            paidCents: 10_404,
+            paidAt: '2026-10-05T18:00:00.000Z',
+            installmentStatus: LoanCredit.LoanInstallmentStatusEnum.PAID,
+            paymentId: '01JPAY',
+        };
+        expect(LoanCredit.INSTALLMENT_PAID_EVENT_TYPE).toBe('InstallmentPaidV1');
+        expect(payload.installmentNumber).toBe(3);
+    });
+});

package/_test_/unit/retailCommission/commissionPayout.test.ts

@@ -0,0 +1,104 @@
+import 'reflect-metadata';
+import * as RetailCommission from '../../../src/retailCommission';
+
+// Caso V-01: $915 de bonos ×1.5, umbral $200, sin ajustes → neto $1,573.
+const breakdown: RetailCommission.CommissionSellerBreakdown = {
+    sellerId: 'V-01',
+    salesCount: 5,
+    unitsCount: 8,
+    placementCents: 1_000_000,
+    subtotalBonusCents: 91_500,
+    multiplierBps: 15_000,
+    multiplierBeforeCapBps: 15_000,
+    multipliers: [{ ruleId: 'RC-05', name: 'Aceleración calidad NPI', factorBps: 15_000 }],
+    thresholdBonusCents: 20_000,
+    thresholds: [{ ruleId: 'RC-07', name: 'Mix de productos', amountCents: 20_000 }],
+    portfolioRentCents: 0,
+    releasedCents: 157_250,
+    adjustmentsCents: 0,
+    clawbackCents: 0,
+    netCents: 157_250,
+    byRule: [{ ruleId: 'RC-01', name: 'Base semanal · ventas 1-5', unitsCount: 5, bonusCents: 40_000, multiplierShareCents: 20_000 }],
+    byStore: [{ storeId: 'ST-1', salesCount: 5, unitsCount: 8, placementCents: 1_000_000, paidCents: 137_250 }],
+    bySku: [{ sku: 'PHONE-A', unitsCount: 1, placementCents: 350_000, paidCents: 12_000 }],
+};
+
+describe('retailCommission — desglose del corte de un vendedor', () => {
+    it('liberado = subtotal × multiplicador + umbral + renta, y neto = liberado + ajustes', () => {
+        const liberado =
+            Math.round((breakdown.subtotalBonusCents * breakdown.multiplierBps) / 10_000) +
+            breakdown.thresholdBonusCents +
+            breakdown.portfolioRentCents;
+        expect(liberado).toBe(breakdown.releasedCents);
+        expect(breakdown.releasedCents + breakdown.adjustmentsCents).toBe(breakdown.netCents);
+    });
+
+    it('el corte de un vendedor puede traer su desglose, y uno viejo sigue siendo válido sin él', () => {
+        const legacy: RetailCommission.CommissionPayoutSeller = {
+            retailerId: 'RET-1',
+            periodId: '2026-09-28',
+            sellerId: 'V-01',
+            accruedCount: 5,
+            baseAmountCents: 91_500,
+            settledAmountCents: null,
+            quotaMet: null,
+            quotaFactorBps: null,
+        };
+        const withBreakdown: RetailCommission.CommissionPayoutSeller = { ...legacy, settledAmountCents: 157_250, breakdown };
+        expect(legacy.breakdown).toBeUndefined();
+        expect(withBreakdown.breakdown?.netCents).toBe(157_250);
+    });
+});
+
+describe('retailCommission — corte vivo, agregados y series', () => {
+    it('expone por qué se agrega y por qué se arma una serie', () => {
+        expect(Object.values(RetailCommission.CommissionAggregateByEnum)).toEqual(['RULE', 'STORE', 'SKU', 'SELLER']);
+        expect(Object.values(RetailCommission.CommissionSeriesByEnum)).toEqual(['SELLER', 'RULE', 'STORE', 'SKU']);
+    });
+
+    it('el corte vivo trae el desglose de cada vendedor y sus ventas sin datos del cliente', () => {
+        const live: RetailCommission.GetLivePayoutResponse = {
+            periodId: '2026-09-28',
+            periodStart: '2026-09-28',
+            periodEnd: '2026-10-04',
+            status: RetailCommission.CommissionPayoutStatusEnum.OPEN,
+            sellers: [breakdown],
+        };
+        const seller: RetailCommission.GetLiveSellerResponse = {
+            periodId: '2026-09-28',
+            seller: breakdown,
+            sales: [
+                {
+                    saleId: 'S1',
+                    soldAt: '2026-09-28T18:00:00.000Z',
+                    storeId: 'ST-1',
+                    status: RetailCommission.CommissionAccrualStatusEnum.ACCRUED,
+                    planSnapshotId: 'SNAP-1',
+                    lines: [],
+                    appliedBonuses: [],
+                    subtotalBonusCents: 8000,
+                },
+            ],
+        };
+        expect(live.sellers).toHaveLength(1);
+        expect(seller.sales[0]?.subtotalBonusCents).toBe(8000);
+    });
+
+    it('agregados y series salen de los cortes cerrados', () => {
+        const aggregates: RetailCommission.GetPayoutAggregatesResponse = {
+            by: RetailCommission.CommissionAggregateByEnum.RULE,
+            from: '2026-09-07',
+            to: '2026-09-28',
+            periodIds: ['2026-09-07', '2026-09-14', '2026-09-21', '2026-09-28'],
+            rows: [{ key: 'RC-01', name: 'Base semanal · ventas 1-5', sellersCount: 12, salesCount: 0, unitsCount: 140, placementCents: 0, paidCents: 1_120_000 }],
+            totalPaidCents: 1_120_000,
+        };
+        const series: RetailCommission.GetPayoutSeriesResponse = {
+            by: RetailCommission.CommissionSeriesByEnum.SELLER,
+            id: 'V-01',
+            points: [{ periodId: '2026-09-28', salesCount: 5, unitsCount: 8, placementCents: 1_000_000, paidCents: 157_250 }],
+        };
+        expect(aggregates.rows[0]?.paidCents).toBe(aggregates.totalPaidCents);
+        expect(series.points).toHaveLength(1);
+    });
+});

package/_test_/unit/retailCommission/commissionRent.test.ts

@@ -0,0 +1,33 @@
+import 'reflect-metadata';
+import * as RetailCommission from '../../../src/retailCommission';
+
+const { CommissionAccrualStatusEnum, CommissionBonusModeEnum } = RetailCommission;
+
+describe('retailCommission — renta de cartera', () => {
+    it('una cuota pagada devenga un bono por cada regla de renta que le aplica', () => {
+        const coupon: RetailCommission.CommissionCouponAccrual = {
+            sellerId: 'V-01',
+            retailerId: 'RET-1',
+            periodId: '2026-10-05',
+            creditId: 'CR-1',
+            saleId: 'S-1',
+            installmentNumber: 3,
+            couponAmountCents: 10_404,
+            paidAt: '2026-10-05T18:00:00.000Z',
+            planSnapshotId: 'SNAP-1',
+            bonuses: [{ ruleId: 'RC-13', name: 'Renta gama alta', mode: CommissionBonusModeEnum.PERCENT, amountCents: 104 }],
+            subtotalCents: 104,
+            status: CommissionAccrualStatusEnum.ACCRUED,
+            createdAt: '2026-10-05T18:00:05.000Z',
+        };
+        expect(coupon.subtotalCents).toBe(coupon.bonuses[0]?.amountCents);
+    });
+
+    it('el desglose puede traer la renta por regla y el NPI; uno anterior a la renta sigue siendo válido', () => {
+        const rent: RetailCommission.CommissionAppliedRent = { ruleId: 'RC-13', name: 'Renta gama alta', couponsCount: 2, amountCents: 208 };
+        const partial: Partial<RetailCommission.CommissionSellerBreakdown> = { rentByRule: [rent], npiM30Bps: 250, npiSample: 8 };
+        const legacy: Partial<RetailCommission.CommissionSellerBreakdown> = {};
+        expect(partial.rentByRule?.[0]?.couponsCount).toBe(2);
+        expect(legacy.npiM30Bps).toBeUndefined();
+    });
+});

package/_test_/unit/retailCommission/commissionRules.test.ts

@@ -0,0 +1,249 @@
+import 'reflect-metadata';
+import * as RetailCommission from '../../../src/retailCommission';
+import * as RetailCatalog from '../../../src/retailCatalog';
+import * as RetailWizard from '../../../src/retailWizard';
+
+describe('retailCommission — enums de las reglas', () => {
+    it('expone los estados de una regla', () => {
+        expect(Object.values(RetailCommission.CommissionRuleStatusEnum)).toEqual([
+            'DRAFT', 'SCHEDULED', 'ACTIVE', 'PAUSED', 'EXPIRED',
+        ]);
+    });
+
+    it('expone los modos del bono', () => {
+        expect(Object.values(RetailCommission.CommissionBonusModeEnum)).toEqual(['FIXED', 'PERCENT']);
+    });
+
+    it('expone las métricas de condición', () => {
+        expect(Object.values(RetailCommission.CommissionMetricEnum)).toEqual([
+            'POSICION_VENTA_EN_PERIODO', 'COLOCACION_PERIODO', 'NPI_M30_VENDEDOR', 'SKUS_DISTINTOS_PERIODO',
+        ]);
+    });
+
+    it('expone los operadores de condición', () => {
+        expect(Object.values(RetailCommission.CommissionOperatorEnum)).toEqual(['GTE', 'LTE', 'LT', 'GT', 'BETWEEN', 'IN']);
+    });
+
+    it('expone las ventanas del corte', () => {
+        expect(Object.values(RetailCommission.CommissionWindowEnum)).toEqual(['SEMANA_OPERATIVA', 'ROLLING_7D', 'MES']);
+    });
+
+    it('agrega el paso del bono por venta a la traza sin quitar los existentes', () => {
+        expect(Object.values(RetailCommission.CommissionCalcStepEnum)).toEqual([
+            'MECHANIC', 'EXCEPTION', 'ADDON', 'QUOTA', 'ADJUSTMENT', 'NO_CATEGORY', 'BONUS_PER_SALE',
+        ]);
+    });
+});
+
+describe('retailCommission — regla, políticas y snapshot', () => {
+    const { CommissionBonusModeEnum, CommissionMetricEnum, CommissionOperatorEnum, CommissionRuleStatusEnum, CommissionWindowEnum } =
+        RetailCommission;
+
+    // Base semanal: $80 por cada una de las primeras 5 piezas de la semana.
+    const base: RetailCommission.CommissionRule = {
+        ruleId: '01JRULE0000000000000000001',
+        retailerId: 'RET-1',
+        name: 'Base semanal · ventas 1-5',
+        description: null,
+        status: CommissionRuleStatusEnum.ACTIVE,
+        levers: {
+            bonoPorVenta: { mode: CommissionBonusModeEnum.FIXED, value: 8000 },
+            bonoUmbral: null,
+            multiplicador: null,
+            bonoPorCuponPagado: null,
+        },
+        scope: { tipos: [], gamas: [], skus: [], tiendas: [] },
+        condition: {
+            metric: CommissionMetricEnum.POSICION_VENTA_EN_PERIODO,
+            operator: CommissionOperatorEnum.BETWEEN,
+            value: [1, 5],
+            minSample: null,
+        },
+        effectiveFrom: '2026-09-28',
+        effectiveTo: null,
+        priority: 100,
+        replacesOthers: false,
+        version: 1,
+        publishedVersion: 1,
+        publishedBy: 'admin-1',
+        publishedAt: '2026-09-28T15:00:00.000Z',
+        createdBy: 'admin-1',
+        updatedBy: 'admin-1',
+        createdAt: '2026-09-28T14:00:00.000Z',
+        updatedAt: '2026-09-28T15:00:00.000Z',
+    };
+
+    it('una regla puede llevar las cuatro palancas y un alcance con los enums del catálogo', () => {
+        const npi: RetailCommission.CommissionRule = {
+            ...base,
+            levers: {
+                bonoPorVenta: null,
+                bonoUmbral: { amountCents: 20000 },
+                multiplicador: { factorBps: 15000 },
+                bonoPorCuponPagado: { mode: CommissionBonusModeEnum.PERCENT, value: 100 },
+            },
+            scope: {
+                tipos: [RetailCatalog.ProductCategoryEnum.PHONE],
+                gamas: [RetailCatalog.ProductTierEnum.HIGH],
+                skus: ['SKU-1'],
+                tiendas: ['ST-1'],
+            },
+            condition: { metric: CommissionMetricEnum.NPI_M30_VENDEDOR, operator: CommissionOperatorEnum.LT, value: 300, minSample: 5 },
+            replacesOthers: true,
+        };
+        expect(npi.levers.multiplicador?.factorBps).toBe(15000);
+        expect(npi.condition?.minSample).toBe(5);
+    });
+
+    it('el snapshot congela las reglas publicadas y las políticas', () => {
+        const snapshot: RetailCommission.CommissionRuleSetSnapshot = {
+            retailerId: 'RET-1',
+            snapshotId: '01JSNAP000000000000000001',
+            rules: [base],
+            policies: {
+                clawback: { cancelacionDias: 7, devolucionDias: 7, npiM30Dias: 30, editedBy: 'admin-1', editedAt: '2026-09-28T15:00:00.000Z' },
+                commissions: {
+                    multiplicadorMaxBps: 25000,
+                    ventanaDefault: CommissionWindowEnum.SEMANA_OPERATIVA,
+                    editedBy: 'admin-1',
+                    editedAt: '2026-09-28T15:00:00.000Z',
+                },
+            },
+            changeNote: 'Publica Base semanal · ventas 1-5',
+            publishedBy: 'admin-1',
+            publishedAt: '2026-09-28T15:00:00.000Z',
+        };
+        expect(snapshot.rules).toHaveLength(1);
+    });
+
+    it('las políticas pueden faltar mientras la cadena no las guarda', () => {
+        const policies: RetailCommission.CommissionPolicies = { clawback: null, commissions: null };
+        expect(policies.clawback).toBeNull();
+    });
+});
+
+describe('retailCommission — devengo con reglas', () => {
+    const { CommissionBonusModeEnum, CommissionCalcStepEnum } = RetailCommission;
+
+    const phone: RetailCommission.CommissionSaleLine = {
+        lineId: 'L1',
+        sku: 'SKU-PHONE',
+        qty: 1,
+        netCents: 450000,
+        category: RetailCatalog.ProductCategoryEnum.PHONE,
+        tier: RetailCatalog.ProductTierEnum.HIGH,
+        brand: 'Samsung',
+        paymentType: RetailWizard.LinePaymentTypeEnum.CREDIT,
+    };
+    const gift: RetailCommission.CommissionSaleLine = {
+        ...phone,
+        lineId: 'L2',
+        netCents: 0,
+        role: RetailWizard.WizardLineRoleEnum.GIFT,
+    };
+
+    const sale: RetailCommission.CommissionSaleInput = {
+        saleId: 'SALE-1',
+        sellerId: 'SELLER-1',
+        retailerId: 'RET-1',
+        storeId: 'ST-1',
+        sku: 'SKU-PHONE',
+        brand: 'Samsung',
+        equipmentPriceCents: 450000,
+        amountCents: 450000,
+        financier: RetailWizard.SaleFinancierEnum.SUREKEEP,
+        paymentType: 'CREDIT',
+        soldAt: '2026-09-30T18:00:00.000Z',
+        lines: [phone, gift],
+    };
+
+    it('la venta lleva sus líneas, y una sin líneas sigue siendo válida', () => {
+        const legacy: RetailCommission.CommissionSaleInput = {
+            saleId: sale.saleId,
+            sellerId: sale.sellerId,
+            retailerId: sale.retailerId,
+            storeId: sale.storeId,
+            sku: sale.sku,
+            brand: sale.brand,
+            equipmentPriceCents: sale.equipmentPriceCents,
+            amountCents: sale.amountCents,
+            financier: sale.financier,
+            paymentType: sale.paymentType,
+            soldAt: sale.soldAt,
+        };
+        expect(sale.lines).toHaveLength(2);
+        expect(legacy.lines).toBeUndefined();
+    });
+
+    it('el bono aplicado dice qué regla, qué pieza y en qué posición', () => {
+        const bonus: RetailCommission.CommissionAppliedBonus = {
+            ruleId: '01JRULE0000000000000000001',
+            name: 'Base semanal · ventas 1-5',
+            lineId: 'L1',
+            sku: 'SKU-PHONE',
+            position: 1,
+            mode: CommissionBonusModeEnum.FIXED,
+            amountCents: 8000,
+        };
+        const trace: RetailCommission.CommissionCalcTraceEntry = {
+            step: CommissionCalcStepEnum.BONUS_PER_SALE,
+            label: bonus.name,
+            outputCents: bonus.amountCents,
+            detail: { ruleId: bonus.ruleId, lineId: bonus.lineId, position: bonus.position },
+        };
+        expect(trace.outputCents).toBe(8000);
+    });
+
+    it('el devengo puede traer los bonos aplicados y su subtotal', () => {
+        const accrual: Pick<RetailCommission.CommissionAccrual, 'appliedBonuses' | 'subtotalBonusCents'> = {
+            appliedBonuses: [],
+            subtotalBonusCents: 0,
+        };
+        expect(accrual.subtotalBonusCents).toBe(0);
+    });
+});
+
+describe('retailCommission — contratos de reglas y políticas', () => {
+    const { CommissionBonusModeEnum, CommissionWindowEnum } = RetailCommission;
+
+    const input: RetailCommission.CommissionRuleInput = {
+        name: 'Bono Accesorios',
+        description: null,
+        levers: {
+            bonoPorVenta: { mode: CommissionBonusModeEnum.FIXED, value: 1000 },
+            bonoUmbral: null,
+            multiplicador: null,
+            bonoPorCuponPagado: null,
+        },
+        scope: { tipos: [RetailCatalog.ProductCategoryEnum.ACCESSORY], gamas: [], skus: [], tiendas: [] },
+        condition: null,
+        effectiveFrom: '2026-10-01',
+        effectiveTo: null,
+        priority: 100,
+        replacesOthers: false,
+    };
+
+    it('crear y editar comparten el cuerpo; editar exige la versión que se cargó', () => {
+        const create: RetailCommission.CreateRuleRequest = input;
+        const update: RetailCommission.UpdateRuleRequest = { ...input, expectedVersion: 2 };
+        const action: RetailCommission.RuleActionRequest = { expectedVersion: 3 };
+        expect([create.name, update.expectedVersion, action.expectedVersion]).toEqual(['Bono Accesorios', 2, 3]);
+    });
+
+    it('las políticas se guardan juntas', () => {
+        const request: RetailCommission.UpdatePoliciesRequest = {
+            clawback: { cancelacionDias: 7, devolucionDias: 7, npiM30Dias: 30 },
+            commissions: { multiplicadorMaxBps: 25000, ventanaDefault: CommissionWindowEnum.SEMANA_OPERATIVA },
+        };
+        expect(request.commissions.multiplicadorMaxBps).toBe(25000);
+    });
+
+    it('el plan vigente con reglas puede no existir todavía', () => {
+        const response: RetailCommission.GetRuleSetResponse = { active: null };
+        const history: RetailCommission.RuleHistoryResponse = {
+            events: [{ at: '2026-10-01T15:00:00.000Z', action: 'PUBLISH', performedBy: 'admin-1', version: 1 }],
+        };
+        expect(response.active).toBeNull();
+        expect(history.events[0]?.version).toBe(1);
+    });
+});

package/_test_/unit/retailCommission/commissionSimulation.test.ts

@@ -0,0 +1,43 @@
+import 'reflect-metadata';
+import * as RetailCommission from '../../../src/retailCommission';
+import * as RetailCatalog from '../../../src/retailCatalog';
+
+describe('retailCommission — simulador de reglas', () => {
+    it('expone por qué una regla no paga en la simulación', () => {
+        expect(Object.values(RetailCommission.CommissionSimulationSkipEnum)).toEqual([
+            'NOT_IN_EFFECT', 'OUT_OF_SCOPE', 'CONDITION_NOT_MET', 'NO_DATA',
+        ]);
+    });
+
+    it('la simulación lleva un vendedor modelo y un producto, y devuelve venta siguiente, progresión y corte', () => {
+        const request: RetailCommission.SimulateRulesRequest = {
+            ruleIds: [],
+            profile: { unitsInWeek: 7, placementCents: 2_800_000, distinctSkus: 2 },
+            product: { sku: 'PHONE-A', category: RetailCatalog.ProductCategoryEnum.PHONE, tier: RetailCatalog.ProductTierEnum.MID, netCents: 350_000 },
+            storeId: null,
+            date: null,
+        };
+        const response: RetailCommission.SimulateRulesResponse = {
+            date: '2026-10-01',
+            nextSale: {
+                position: 8,
+                subtotalBonusCents: 15_000,
+                rules: [
+                    { ruleId: 'RC-02', name: 'Extendido', amountCents: 15_000, skipped: null },
+                    { ruleId: 'RC-24', name: 'Accesorios', amountCents: 0, skipped: RetailCommission.CommissionSimulationSkipEnum.OUT_OF_SCOPE },
+                ],
+            },
+            progression: [{ position: 1, subtotalBonusCents: 8_000, cumulativeBonusCents: 8_000 }],
+            week: {
+                subtotalBonusCents: 70_000,
+                multiplierBps: 15_000,
+                multiplierBeforeCapBps: 15_000,
+                multipliers: [],
+                thresholdBonusCents: 0,
+                thresholds: [],
+                releasedCents: 105_000,
+            },
+        };
+        expect(request.profile.unitsInWeek + 1).toBe(response.nextSale.position);
+    });
+});

package/_test_/unit/retailCommission/myCommissions.test.ts

@@ -0,0 +1,29 @@
+import 'reflect-metadata';
+import * as RetailCommission from '../../../src/retailCommission';
+
+describe('retailCommission — mis comisiones', () => {
+    it('el vendedor ve su semana, mes, año, sus últimos cortes y las reglas vigentes', () => {
+        const mine: RetailCommission.GetMyCommissionsResponse = {
+            seller: { sellerId: 'V-01', name: 'Ana López', storeId: 'ST-1' },
+            period: { periodId: '2026-10-05', periodStart: '2026-10-05', periodEnd: '2026-10-11' },
+            week: null,
+            month: { periodsCount: 1, salesCount: 7, unitsCount: 9, netCents: 157_250 },
+            year: { periodsCount: 20, salesCount: 140, unitsCount: 180, netCents: 2_400_000 },
+            history: [{ periodId: '2026-09-28', salesCount: 7, unitsCount: 9, placementCents: 1_000_000, paidCents: 157_250 }],
+            rules: [
+                {
+                    ruleId: 'RC-07',
+                    name: 'Mix de productos',
+                    description: null,
+                    levers: { bonoPorVenta: null, bonoUmbral: { amountCents: 20_000 }, multiplicador: null, bonoPorCuponPagado: null },
+                    scope: { tipos: [], gamas: [], skus: [], tiendas: [] },
+                    condition: null,
+                    effectiveFrom: '2026-09-01',
+                    effectiveTo: null,
+                },
+            ],
+            multiplierCapBps: 25_000,
+        };
+        expect(mine.history[0]?.paidCents).toBe(mine.month.netCents);
+    });
+});

package/_test_/unit/retailWizard/ventaSagaMessages.test.ts

@@ -2,12 +2,16 @@ import 'reflect-metadata';
 import { plainToInstance, type ClassConstructor } from 'class-transformer';
 import { validateSync, type ValidationError } from 'class-validator';
 import {
+  ExternalProviderEnum,
+  LinePaymentTypeEnum,
   RetailCommissionInboundMessage,
+  RetailCommissionInboundMessageTypeEnum,
   RetailPromotionInboundMessage,
   RetailPromotionInboundMessageTypeEnum,
+  SaleTypeEnum,
   WizardLineRoleEnum,
 } from '../../../src/retailWizard';
-import { ItemTypeEnum } from '../../../src/retailCatalog';
+import { ItemTypeEnum, ProductCategoryEnum, ProductTierEnum } from '../../../src/retailCatalog';
 
 function paths(errors: ValidationError[], prefix = ''): string[] {
   return errors.flatMap((e) => {
@@ -133,33 +137,126 @@ describe('RetailPromotionInboundMessage', () => {
   });
 });
 
+describe('RetailCommissionInboundMessageTypeEnum', () => {
+  it('distingue venta y cancelación', () => {
+    expect(Object.values(RetailCommissionInboundMessageTypeEnum)).toEqual(['SALE_COMPLETED', 'SALE_CANCELLED']);
+  });
+});
+
 describe('RetailCommissionInboundMessage', () => {
+  const phone = {
+    lineId: 'L1',
+    sku: 'PHONE-1',
+    qty: 1,
+    netCents: 299900,
+    itemType: ItemTypeEnum.PRODUCT,
+    category: ProductCategoryEnum.PHONE,
+    tier: ProductTierEnum.HIGH,
+    brand: 'Samsung',
+    paymentType: LinePaymentTypeEnum.CREDIT,
+  };
+  const service = {
+    lineId: 'L2',
+    sku: 'SVC-1',
+    qty: 1,
+    netCents: 9900,
+    itemType: ItemTypeEnum.SERVICE,
+    category: null,
+    tier: null,
+    brand: null,
+    paymentType: LinePaymentTypeEnum.CASH,
+  };
+  const gift = {
+    ...service,
+    lineId: 'L3',
+    sku: 'CASE-1',
+    netCents: 0,
+    itemType: ItemTypeEnum.PRODUCT,
+    category: ProductCategoryEnum.ACCESSORY,
+    role: WizardLineRoleEnum.GIFT,
+  };
   const ok = {
+    type: RetailCommissionInboundMessageTypeEnum.SALE_COMPLETED,
     tenantId: 't',
     retailerId: 'ret',
     storeId: 'st',
     saleId: 'sale-1',
     sessionId: 'ses-1',
+    sellerRetailUserId: 'seller-1',
+    saleType: SaleTypeEnum.CREDIT,
+    externalProvider: null,
+    creditId: 'cred-1',
     soldAt: '2026-09-28T20:00:00.000Z',
-    lines: [
-      { sku: 'PHONE-1', qty: 1, netCents: 299900, itemType: ItemTypeEnum.PRODUCT },
-      { sku: 'SVC-1', qty: 1, netCents: 9900, itemType: ItemTypeEnum.SERVICE },
-    ],
+    occurredAt: '2026-09-28T20:00:00.000Z',
+    lines: [phone, service, gift],
   };
 
-  it('acepta la venta con sus líneas', () => expect(errorsOf(RetailCommissionInboundMessage, ok)).toEqual([]));
+  it('acepta la venta a crédito con sus líneas', () => expect(errorsOf(RetailCommissionInboundMessage, ok)).toEqual([]));
 
-  it('exige la identidad de la venta', () => {
-    const { saleId: _s, soldAt: _so, ...rest } = ok;
-    expect(errorsOf(RetailCommissionInboundMessage, rest)).toEqual(expect.arrayContaining(['saleId', 'soldAt']));
+  it('acepta una derivada a financiera externa sin crédito', () =>
+    expect(
+      errorsOf(RetailCommissionInboundMessage, {
+        ...ok,
+        saleType: SaleTypeEnum.EXTERNAL_REFERRAL,
+        externalProvider: ExternalProviderEnum.PAYJOY,
+        creditId: null,
+      }),
+    ).toEqual([]));
+
+  it('acepta una cancelación con su motivo', () =>
+    expect(
+      errorsOf(RetailCommissionInboundMessage, {
+        ...ok,
+        type: RetailCommissionInboundMessageTypeEnum.SALE_CANCELLED,
+        occurredAt: '2026-09-29T15:00:00.000Z',
+        cancelReason: 'el cliente se arrepintió',
+      }),
+    ).toEqual([]));
+
+  it('la cancelación sin motivo también vale', () => {
+    const cancelled = { ...ok, type: RetailCommissionInboundMessageTypeEnum.SALE_CANCELLED };
+    expect(errorsOf(RetailCommissionInboundMessage, cancelled)).toEqual([]);
+    expect(errorsOf(RetailCommissionInboundMessage, { ...cancelled, cancelReason: '' })).toEqual([]);
+  });
+
+  it('exige el tipo de mensaje, el vendedor, el tipo de venta y la identidad', () => {
+    const { type: _t, sellerRetailUserId: _s, saleType: _st, saleId: _id, soldAt: _so, occurredAt: _o, ...rest } = ok;
+    expect(errorsOf(RetailCommissionInboundMessage, rest)).toEqual(
+      expect.arrayContaining(['type', 'sellerRetailUserId', 'saleType', 'saleId', 'soldAt', 'occurredAt']),
+    );
   });
 
   it('rechaza sin líneas', () => expect(errorsOf(RetailCommissionInboundMessage, { ...ok, lines: [] })).toContain('lines'));
 
   it('valida cada línea', () =>
     expect(
-      errorsOf(RetailCommissionInboundMessage, { ...ok, lines: [{ sku: 'X', qty: 0, netCents: -1, itemType: 'KIT' }] }),
-    ).toEqual(expect.arrayContaining(['lines.0.qty', 'lines.0.netCents', 'lines.0.itemType'])));
+      errorsOf(RetailCommissionInboundMessage, {
+        ...ok,
+        lines: [
+          {
+            lineId: '',
+            sku: 'X',
+            qty: 0,
+            netCents: -1,
+            itemType: 'KIT',
+            category: 'CELULAR',
+            tier: 'ORO',
+            brand: null,
+            paymentType: 'TARJETA',
+          },
+        ],
+      }),
+    ).toEqual(
+      expect.arrayContaining([
+        'lines.0.lineId',
+        'lines.0.qty',
+        'lines.0.netCents',
+        'lines.0.itemType',
+        'lines.0.category',
+        'lines.0.tier',
+        'lines.0.paymentType',
+      ]),
+    ));
 });
 
 describe('RetailPromotionInboundMessage — tipos nullables y ids no vacíos', () => {

package/bin/loanCredit/dtos/InstallmentPaidEvent.d.ts

@@ -0,0 +1,18 @@
+import type { LoanInstallmentStatusEnum } from '../enums/LoanInstallmentStatusEnum';
+/** `eventType` del outbox cuando una cuota queda pagada. */
+export declare const INSTALLMENT_PAID_EVENT_TYPE = "InstallmentPaidV1";
+/**
+ * Payload de `InstallmentPaidV1`: una cuota que pasó a `PAID` o `PAID_IN_ADVANCE` por cualquier
+ * camino (cargo de la cuota, revisión, adelanto, liquidación o recuperación). Se escribe al outbox en
+ * la misma transacción que la cuota. Sin PII.
+ */
+export interface InstallmentPaidV1Payload {
+    creditId: string;
+    installmentNumber: number;
+    /** Lo pagado de la cuota en total (capital + interés + IVA), en centavos. */
+    paidCents: number;
+    /** Instante del pago (ISO): decide el corte de la renta. */
+    paidAt: string;
+    installmentStatus: LoanInstallmentStatusEnum;
+    paymentId: string;
+}

package/bin/loanCredit/dtos/InstallmentPaidEvent.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INSTALLMENT_PAID_EVENT_TYPE = void 0;
+/** `eventType` del outbox cuando una cuota queda pagada. */
+exports.INSTALLMENT_PAID_EVENT_TYPE = 'InstallmentPaidV1';

package/bin/loanCredit/index.d.ts

@@ -6,6 +6,7 @@ export * from './dtos/LoanBorrower';
 export * from './dtos/LoanBeneficiary';
 export * from './dtos/LoanCredit';
 export * from './dtos/LoanInstallment';
+export * from './dtos/InstallmentPaidEvent';
 export * from './dtos/LoanContract';
 export * from './dtos/ActivationChecklist';
 export * from './dtos/AppliedPromotionSnapshot';