@fiado/type-kit 3.494.0 → 3.496.0

package/_test_/unit/loanCredit/dtos/createSellerPaymentRequest.test.ts

@@ -0,0 +1,63 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { CreateSellerPaymentRequest } from '../../../../src/loanCredit/index';
+
+const errorPaths = async (body: object): Promise<string[]> => {
+    const dto = plainToInstance(CreateSellerPaymentRequest, body);
+    const errors = await validate(dto, { whitelist: true, forbidNonWhitelisted: false });
+    const pathsOf = (error: (typeof errors)[number], parent: string): string[] => {
+        const path = parent ? `${parent}.${error.property}` : error.property;
+        return [...(error.constraints ? [path] : []), ...(error.children ?? []).flatMap((child) => pathsOf(child, path))];
+    };
+    return errors.flatMap((error) => pathsOf(error, ''));
+};
+
+const BASE = {
+    type: 'NEXT_INSTALLMENT',
+    expectedAmountCents: 48_700,
+    method: 'CASH',
+    idempotencyKey: '7b0e3a52-6a0f-4f1f-9f43-6b4d5c1e2a10',
+};
+
+describe('CreateSellerPaymentRequest', () => {
+    it('acepta efectivo sin detalle', async () => {
+        expect(await errorPaths(BASE)).toEqual([]);
+    });
+
+    it('acepta tarjeta con últimos 4 y autorización', async () => {
+        expect(await errorPaths({ ...BASE, method: 'CARD', detail: { cardLast4: '4242', authCode: 'A1B2C3' } })).toEqual([]);
+    });
+
+    it('acepta SPEI con clave de rastreo de hasta 30', async () => {
+        expect(await errorPaths({ ...BASE, method: 'WIRE', detail: { speiTrackingKey: 'X'.repeat(30) } })).toEqual([]);
+    });
+
+    it('rechaza últimos 4 que no son 4 dígitos', async () => {
+        expect(await errorPaths({ ...BASE, method: 'CARD', detail: { cardLast4: '42a2', authCode: 'A1' } })).toEqual(['detail.cardLast4']);
+    });
+
+    it('rechaza clave de rastreo vacía o de más de 30', async () => {
+        expect(await errorPaths({ ...BASE, method: 'WIRE', detail: { speiTrackingKey: '' } })).toEqual(['detail.speiTrackingKey']);
+        expect(await errorPaths({ ...BASE, method: 'WIRE', detail: { speiTrackingKey: 'X'.repeat(31) } })).toEqual([
+            'detail.speiTrackingKey',
+        ]);
+    });
+
+    it('rechaza forma de pago, tipo, monto o llave inválidos', async () => {
+        expect(await errorPaths({ ...BASE, method: 'CHEQUE' })).toEqual(['method']);
+        expect(await errorPaths({ ...BASE, type: 'OTHER' })).toEqual(['type']);
+        expect(await errorPaths({ ...BASE, expectedAmountCents: 0 })).toEqual(['expectedAmountCents']);
+        expect(await errorPaths({ ...BASE, idempotencyKey: 'no-uuid' })).toEqual(['idempotencyKey']);
+    });
+
+    it('cuotas solo de 2 en adelante', async () => {
+        expect(await errorPaths({ ...BASE, type: 'ADVANCE', installmentCount: 1 })).toEqual(['installmentCount']);
+        expect(await errorPaths({ ...BASE, type: 'ADVANCE', installmentCount: 2 })).toEqual([]);
+    });
+
+    it('no declara CLABE: con whitelist se descarta y nunca llega al dominio', () => {
+        const dto = plainToInstance(CreateSellerPaymentRequest, { ...BASE, clabe: '012345678901234567' }, { excludeExtraneousValues: true });
+        expect(dto).not.toHaveProperty('clabe');
+    });
+});

package/_test_/unit/loanCredit/dtos/originateLoanCreditRequest.test.ts

@@ -0,0 +1,56 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { OriginateLoanCreditRequest } from '../../../../src/loanCredit/dtos/requests/OriginateLoanCreditRequest';
+
+const BASE = {
+    wizardSessionId: 'WS-1',
+    borrowerId: 'B-1',
+    planId: 'PLAN-1',
+    termWeeks: 12,
+    equipmentPriceCents: 500000,
+    downPaymentCents: 100000,
+    storeId: 'ST-1',
+};
+
+/** Igual que `validateRequest` del motor: whitelist sin rechazar extras. */
+const validateWhitelisted = (body: object) => {
+    const dto = plainToInstance(OriginateLoanCreditRequest, body);
+    return validate(dto, { whitelist: true, forbidNonWhitelisted: false }).then((errors) => ({ dto, errors }));
+};
+
+describe('OriginateLoanCreditRequest', () => {
+    it('acepta el request con tienda y vendedor y conserva los dos', async () => {
+        const { dto, errors } = await validateWhitelisted({ ...BASE, sellerId: 'U-1' });
+
+        expect(errors).toEqual([]);
+        expect(dto.storeId).toBe('ST-1');
+        expect(dto.sellerId).toBe('U-1');
+    });
+
+    it('rechaza el request sin tienda: sin ella el motor no resuelve la promoción ni la cartera', async () => {
+        const { storeId: _omitted, ...withoutStore } = BASE;
+        const { errors } = await validateWhitelisted(withoutStore);
+
+        expect(errors.some((error) => error.property === 'storeId')).toBe(true);
+    });
+
+    it('rechaza la tienda vacía', async () => {
+        const { errors } = await validateWhitelisted({ ...BASE, storeId: '' });
+
+        expect(errors.some((error) => error.property === 'storeId')).toBe(true);
+    });
+
+    it('acepta el request sin vendedor: los créditos viejos los llena el backfill', async () => {
+        const { dto, errors } = await validateWhitelisted(BASE);
+
+        expect(errors).toEqual([]);
+        expect(dto.sellerId).toBeUndefined();
+    });
+
+    it('rechaza el vendedor vacío: un sellerId en blanco sería una llave de GSI inválida', async () => {
+        const { errors } = await validateWhitelisted({ ...BASE, sellerId: '' });
+
+        expect(errors.some((error) => error.property === 'sellerId')).toBe(true);
+    });
+});

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

@@ -0,0 +1,141 @@
+import 'reflect-metadata';
+import type {
+    CreditCustomerListItem,
+    InStorePaymentListResponse,
+    LoanPaymentListItem,
+    SellerCreditLookupResult,
+    SellerPaymentOptions,
+    SellerPaymentResult,
+} from '../../../src/loanCredit/index';
+import {
+    CreditCustomerStateEnum,
+    InStorePaymentMethodEnum,
+    LoanCustomerPaymentTypeEnum,
+    LoanInstallmentStatusEnum,
+    LoanPaymentOriginEnum,
+} from '../../../src/loanCredit/index';
+
+describe.each([
+    ['InStorePaymentMethodEnum', InStorePaymentMethodEnum, ['CASH', 'CARD', 'WIRE']],
+    ['LoanPaymentOriginEnum', LoanPaymentOriginEnum, ['COLLECTION_ENGINE', 'IN_STORE']],
+    ['CreditCustomerStateEnum', CreditCustomerStateEnum, ['READ', 'NO_BORROWER', 'UNAVAILABLE']],
+])('%s', (_name, enumObject, values) => {
+    it('tiene exactamente los valores del contrato', () => {
+        expect(Object.values(enumObject).sort()).toEqual([...values].sort());
+    });
+    it('cada llave es igual a su valor', () => {
+        for (const [key, value] of Object.entries(enumObject)) {
+            expect(key).toBe(value);
+        }
+    });
+});
+
+describe('loanCredit — contrato del cobro en tienda', () => {
+    it('el resultado lleva folio, tienda, vendedor, siguiente cuota y equipo', () => {
+        const result: SellerPaymentResult = {
+            creditId: 'CR-1',
+            receipt: 'SK-TD-0123456789ab',
+            amountCents: 48_700,
+            type: LoanCustomerPaymentTypeEnum.NEXT_INSTALLMENT,
+            method: InStorePaymentMethodEnum.CASH,
+            appliedAt: '2026-10-08T17:00:00.000Z',
+            outstandingBalanceAfterCents: 400_000,
+            collectedAtStore: { id: 'ST-1', name: 'Tienda Limpia' },
+            collectedBySeller: { id: 'RU-1', name: 'Ana' },
+            nextInstallment: { installmentNumber: 4, dueDate: '2026-10-15', amountCents: 48_700, status: LoanInstallmentStatusEnum.PENDING },
+            credit: { creditId: 'CR-1', imei: '356789012345678', productBrand: 'Samsung', productModel: 'A15' },
+        };
+        expect(result.receipt.startsWith('SK-TD-')).toBe(true);
+    });
+
+    it('las opciones traen el resumen y cada tipo con su monto o rango', () => {
+        const options: SellerPaymentOptions = {
+            creditId: 'CR-1',
+            summary: { totalCents: 1_000_000, paidCents: 600_000, remainingCents: 400_000, nextInstallment: null },
+            nextInstallment: { available: true, amountCents: 97_400, installmentNumbers: [3, 4], overdueCount: 1 },
+            advance: { available: false, unavailableReason: 'CREDIT_NOT_CURRENT' as never },
+            prepayment: { available: false },
+            settlement: { available: true, amountCents: 380_000 },
+        };
+        expect(options.nextInstallment.installmentNumbers).toEqual([3, 4]);
+    });
+
+    it('la búsqueda responde lo mínimo, sin el identificador que no se buscó', () => {
+        const found: SellerCreditLookupResult = {
+            creditId: 'CR-1',
+            customerName: 'Juan P.',
+            productBrand: 'Samsung',
+            productModel: 'A15',
+            nextInstallment: null,
+        };
+        expect(found).not.toHaveProperty('imei');
+        expect(found).not.toHaveProperty('phone');
+    });
+
+    it('la conciliación pagina los cobros de una tienda', () => {
+        const page: InStorePaymentListResponse = {
+            items: [
+                {
+                    receipt: 'SK-TD-0123456789ab',
+                    creditId: 'CR-1',
+                    paymentId: '01J00000000000000000000000',
+                    chargeKind: 'INSTALLMENT' as never,
+                    amountCents: 48_700,
+                    method: InStorePaymentMethodEnum.CARD,
+                    collectedBySeller: { id: 'RU-1', name: 'Ana' },
+                    appliedAt: '2026-10-08T17:00:00.000Z',
+                },
+            ],
+        };
+        expect(page.nextToken).toBeUndefined();
+    });
+
+    it('el historial dice dónde, cómo y quién; mechanism es opcional', () => {
+        const item: LoanPaymentListItem = {
+            paymentId: 'P-1',
+            receipt: 'SK-TD-0123456789ab',
+            installmentNumber: 3,
+            attemptId: 'IN_STORE#k',
+            result: 'FULL' as never,
+            currency: 'MXN' as never,
+            collectedCents: 48_700,
+            appliedCents: 48_700,
+            overpaidCents: 0,
+            reservedCents: 0,
+            needsReview: false,
+            appliedAt: '2026-10-08T17:00:00.000Z',
+            origin: LoanPaymentOriginEnum.IN_STORE,
+            inStoreMethod: InStorePaymentMethodEnum.CASH,
+            collectedAtStore: { id: 'ST-1', name: 'Tienda Limpia' },
+            collectedBySeller: { id: 'RU-1', name: 'Ana' },
+        };
+        expect(item.mechanism).toBeUndefined();
+    });
+
+    it('la fila de Clientes trae el último pago con su lugar', () => {
+        const row: CreditCustomerListItem = {
+            retailCustomerId: 'RC-1',
+            fullName: null,
+            phone: null,
+            originStoreId: null,
+            segments: [],
+            segmentsRead: true,
+            credit: {
+                state: CreditCustomerStateEnum.READ,
+                clientLevel: null,
+                sciScore: null,
+                sciSource: null,
+                creditsCount: 1,
+                activeCreditsCount: 1,
+                settledCreditsCount: 0,
+                writtenOffCreditsCount: 0,
+                outstandingBalanceCents: 0,
+                arrearsDays: 0,
+                lastPaymentAt: '2026-10-08T17:00:00.000Z',
+                lastPayment: { at: '2026-10-08T17:00:00.000Z', origin: LoanPaymentOriginEnum.IN_STORE, storeId: 'ST-1', storeName: 'Tienda Limpia' },
+                activeCreditId: 'CR-1',
+            },
+        };
+        expect(row.credit.lastPayment?.storeName).toBe('Tienda Limpia');
+    });
+});

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

@@ -0,0 +1,119 @@
+import 'reflect-metadata';
+import type { CreditSaleContext } from '../../../src/loanCredit/index';
+import type { WizardSessionLookupEntry } from '../../../src/retailWizard/index';
+import { WizardSessionLookupStatusEnum } from '../../../src/retailWizard/enums/WizardSessionLookupStatusEnum';
+import {
+    LoanCreditStatusEnum,
+    LoanInstallmentStatusEnum,
+    type SellerCreditDetailResponse,
+    type SellerCreditListResponse,
+    type SellerCreditRow,
+} from '../../../src/loanCredit/index';
+
+describe('loanCredit — contrato de la cartera del vendedor', () => {
+    it('el contexto de venta publica la venta que cerró la sesión', () => {
+        const context: CreditSaleContext = {
+            status: WizardSessionLookupStatusEnum.OK,
+            retailCustomerId: 'RC-1',
+            retailCustomerStatus: WizardSessionLookupStatusEnum.OK,
+            customerName: null,
+            customerNameStatus: WizardSessionLookupStatusEnum.OK,
+            productBrand: 'Samsung',
+            productModel: 'A15',
+            productCapacity: null,
+            retailerId: 'R-1',
+            storeId: 'ST-1',
+            storeName: null,
+            storeNameStatus: WizardSessionLookupStatusEnum.OK,
+            saleId: 'S-1',
+        };
+
+        expect(context.saleId).toBe('S-1');
+    });
+
+    it('la entrada del lote del wizard publica al vendedor de la sesión', () => {
+        const entry: WizardSessionLookupEntry = {
+            wizardSessionId: 'WS-1',
+            status: WizardSessionLookupStatusEnum.OK,
+            sellerRetailUserId: 'U-1',
+        };
+
+        expect(entry.sellerRetailUserId).toBe('U-1');
+    });
+
+    const saleContext: CreditSaleContext = {
+        status: WizardSessionLookupStatusEnum.OK,
+        retailCustomerId: 'RC-1',
+        retailCustomerStatus: WizardSessionLookupStatusEnum.OK,
+        customerName: 'Ana López',
+        customerNameStatus: WizardSessionLookupStatusEnum.OK,
+        productBrand: 'Samsung',
+        productModel: 'A15',
+        productCapacity: null,
+        retailerId: 'R-1',
+        storeId: 'ST-1',
+        storeName: null,
+        storeNameStatus: WizardSessionLookupStatusEnum.OK,
+        saleId: 'S-1',
+    };
+
+    it('la fila de la cartera lleva el resumen del plan y la cuota vigente', () => {
+        const row: SellerCreditRow = {
+            creditId: 'CR-1',
+            status: LoanCreditStatusEnum.ACTIVE,
+            termWeeks: 12,
+            equipmentPriceCents: 500000,
+            imei: '356789012345678',
+            createdAt: '2026-09-01T00:00:00.000Z',
+            summaryUnavailable: false,
+            paidInstallments: 1,
+            outstandingBalanceCents: 300000,
+            overdueDays: 0,
+            overdueAmountCents: 0,
+            currentInstallment: {
+                creditId: 'CR-1',
+                installmentNumber: 2,
+                status: LoanInstallmentStatusEnum.PENDING,
+                dueDate: '2026-10-05',
+                capitalCents: 8000,
+                interestCents: 1500,
+                ivaCents: 500,
+                totalCents: 10000,
+                outstandingBalanceCents: 10000,
+            },
+            saleContext,
+        };
+        const list: SellerCreditListResponse = { items: [row], count: 1, truncated: false };
+
+        expect(list.items[0]?.currentInstallment?.installmentNumber).toBe(2);
+    });
+
+    it('la fila sin plan legible declara summaryUnavailable y deja las cifras en null', () => {
+        const row: SellerCreditRow = {
+            creditId: 'CR-2',
+            status: LoanCreditStatusEnum.IN_ARREARS,
+            termWeeks: 12,
+            equipmentPriceCents: 500000,
+            createdAt: '2026-09-01T00:00:00.000Z',
+            summaryUnavailable: true,
+            paidInstallments: null,
+            outstandingBalanceCents: null,
+            overdueDays: null,
+            overdueAmountCents: null,
+            currentInstallment: null,
+            saleContext,
+        };
+
+        expect(row.paidInstallments).toBeNull();
+    });
+
+    it('el detalle es el crédito, su plan y sus últimos cobros', () => {
+        const detail: SellerCreditDetailResponse = {
+            credit: {} as SellerCreditDetailResponse['credit'],
+            installments: [],
+            recentPayments: [],
+        };
+
+        expect(detail.recentPayments).toEqual([]);
+    });
+});

package/_test_/unit/retailIntegration/applyRetailEventRequest.test.ts

@@ -0,0 +1,43 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+    ApplyInventoryEventRequest,
+    ApplyProductEventRequest,
+    ApplyRetailUserEventRequest,
+    ApplyStoreEventRequest,
+} from '../../../src/retailIntegration/dtos/ApplyRetailEventRequest';
+
+const base = {
+    tenantId: 'surekeep',
+    eventId: 'evt_01J8ZA1B2C3D4E5F6G7H8J9K0L',
+    occurredAt: '2026-08-01T15:00:00Z',
+    payload: { storeId: '12' },
+};
+
+async function propertiesWithErrors(cls: new () => object, plain: Record<string, unknown>): Promise<string[]> {
+    const errors = await validate(plainToInstance(cls, plain));
+    return errors.map((error) => error.property);
+}
+
+describe('DTOs del contrato connector → destino', () => {
+    it.each([
+        [ApplyStoreEventRequest, 'StoreCreatedV1', 'RetailUserCreatedV1'],
+        [ApplyRetailUserEventRequest, 'RetailUserTransferredV1', 'StoreCreatedV1'],
+        [ApplyProductEventRequest, 'ProductCreatedV1', 'InventoryMovementV1'],
+        [ApplyInventoryEventRequest, 'InventoryMovementV1', 'ProductUpdatedV1'],
+    ])('%p acepta %s y rechaza %s de otra ruta', async (cls, own, foreign) => {
+        expect(await propertiesWithErrors(cls, { ...base, eventType: own })).toEqual([]);
+        expect(await propertiesWithErrors(cls, { ...base, eventType: foreign })).toEqual(['eventType']);
+    });
+
+    it.each([ApplyStoreEventRequest, ApplyRetailUserEventRequest, ApplyProductEventRequest, ApplyInventoryEventRequest])(
+        '%p valida tenantId',
+        async (cls) => {
+            const eventType = { ApplyStoreEventRequest: 'StoreCreatedV1', ApplyRetailUserEventRequest: 'RetailUserCreatedV1', ApplyProductEventRequest: 'ProductCreatedV1', ApplyInventoryEventRequest: 'InventoryMovementV1' }[cls.name];
+            for (const tenantId of [undefined, '', 'sure/keep', 'a'.repeat(65)]) {
+                expect(await propertiesWithErrors(cls, { ...base, eventType, tenantId })).toEqual(['tenantId']);
+            }
+        },
+    );
+});

package/_test_/unit/retailIntegration/isIsoDateTimeWithZone.test.ts

@@ -0,0 +1,85 @@
+import 'reflect-metadata';
+import { IsIsoDateTimeWithZone } from '../../../src/retailIntegration/validators/IsIsoDateTimeWithZone';
+import {
+    InventoryEventTypeEnum,
+    ProductEventTypeEnum,
+    RetailEventResultEnum,
+    RetailUserEventTypeEnum,
+    StoreEventTypeEnum,
+} from '../../../src/retailIntegration/enums';
+import {
+    RETAIL_EVENT_ID_MAX_LENGTH,
+    RETAIL_LIST_LIMIT_MAX,
+    RETAIL_LIST_LIMIT_MIN,
+    RETAIL_TENANT_ID_PATTERN,
+} from '../../../src/retailIntegration/constants/retailIntegrationLimits';
+
+describe('IsIsoDateTimeWithZone', () => {
+    const validator = new IsIsoDateTimeWithZone();
+
+    it.each([
+        '2026-08-17T20:32:05Z',
+        '2026-08-17T20:32:05.123Z',
+        '2026-08-17T20:32:05-06:00',
+        '2026-08-17T20:32:05+05:30',
+    ])('acepta %s', (value) => {
+        expect(validator.validate(value)).toBe(true);
+    });
+
+    it.each([
+        ['sin zona', '2026-08-17T20:32:05'],
+        ['solo fecha', '2026-08-17'],
+        ['sin segundos', '2026-08-17T20:32Z'],
+        ['mes inválido', '2026-13-01T00:00:00Z'],
+        ['hora inválida', '2026-08-17T25:00:00Z'],
+        ['31 de febrero', '2026-02-31T00:00:00Z'],
+        ['31 de abril', '2026-04-31T10:00:00-06:00'],
+        ['texto', 'ayer'],
+        ['vacío', ''],
+        ['espacios', '   '],
+    ])('rechaza %s', (_label, value) => {
+        expect(validator.validate(value)).toBe(false);
+    });
+
+    it.each([null, undefined, 1786998725000, {}, []])('rechaza tipos que no son string: %p', (value) => {
+        expect(validator.validate(value)).toBe(false);
+    });
+
+    it('explica el formato esperado en el mensaje', () => {
+        expect(validator.defaultMessage()).toContain('ISO-8601 con zona');
+    });
+});
+
+describe('enums de retailIntegration', () => {
+    it('los resultados son los de la doc', () => {
+        expect(Object.values(RetailEventResultEnum)).toEqual(['APPLIED', 'NOOP', 'REJECTED']);
+    });
+
+    it('los eventType por ruta son los de la doc', () => {
+        expect(Object.values(StoreEventTypeEnum)).toEqual(['StoreCreatedV1', 'StoreUpdatedV1', 'StoreStatusChangedV1']);
+        expect(Object.values(ProductEventTypeEnum)).toEqual(['ProductCreatedV1', 'ProductUpdatedV1', 'ProductStatusChangedV1']);
+        expect(Object.values(InventoryEventTypeEnum)).toEqual(['InventoryMovementV1']);
+        expect(Object.values(RetailUserEventTypeEnum)).toEqual([
+            'RetailUserCreatedV1',
+            'RetailUserUpdatedV1',
+            'RetailUserTransferredV1',
+            'RetailUserStatusChangedV1',
+        ]);
+    });
+});
+
+describe('límites de retailIntegration', () => {
+    it('fija los topes del contrato', () => {
+        expect(RETAIL_EVENT_ID_MAX_LENGTH).toBe(1024);
+        expect(RETAIL_LIST_LIMIT_MIN).toBe(1);
+        expect(RETAIL_LIST_LIMIT_MAX).toBe(200);
+    });
+
+    it('el patrón de tenantId acepta slugs y rechaza separadores de ruta', () => {
+        expect(RETAIL_TENANT_ID_PATTERN.test('surekeep')).toBe(true);
+        expect(RETAIL_TENANT_ID_PATTERN.test('tenant_2-a')).toBe(true);
+        expect(RETAIL_TENANT_ID_PATTERN.test('sure/keep')).toBe(false);
+        expect(RETAIL_TENANT_ID_PATTERN.test('')).toBe(false);
+        expect(RETAIL_TENANT_ID_PATTERN.test('a'.repeat(65))).toBe(false);
+    });
+});

package/_test_/unit/retailIntegration/receiveRetailEventRequest.test.ts

@@ -0,0 +1,93 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { ReceiveStoreEventRequest } from '../../../src/retailIntegration/dtos/ReceiveStoreEventRequest';
+import { ReceiveRetailUserEventRequest } from '../../../src/retailIntegration/dtos/ReceiveRetailUserEventRequest';
+import { ReceiveProductEventRequest } from '../../../src/retailIntegration/dtos/ReceiveProductEventRequest';
+import { ReceiveInventoryEventRequest } from '../../../src/retailIntegration/dtos/ReceiveInventoryEventRequest';
+
+const base = {
+    eventId: 'evt_01J8ZA1B2C3D4E5F6G7H8J9K0L',
+    occurredAt: '2026-08-01T15:00:00Z',
+    payload: { storeId: '12', name: 'Sucursal Centro' },
+};
+
+async function propertiesWithErrors(cls: new () => object, plain: Record<string, unknown>): Promise<string[]> {
+    const errors = await validate(plainToInstance(cls, plain));
+    return errors.map((error) => error.property);
+}
+
+describe('DTOs de entrada de los webhooks', () => {
+    it.each([
+        [ReceiveStoreEventRequest, 'StoreStatusChangedV1'],
+        [ReceiveRetailUserEventRequest, 'RetailUserTransferredV1'],
+        [ReceiveProductEventRequest, 'ProductCreatedV1'],
+        [ReceiveInventoryEventRequest, 'InventoryMovementV1'],
+    ])('%p acepta un sobre válido con %s', async (cls, eventType) => {
+        expect(await propertiesWithErrors(cls, { ...base, eventType })).toEqual([]);
+    });
+
+    it.each([
+        [ReceiveStoreEventRequest, 'RetailUserCreatedV1'],
+        [ReceiveRetailUserEventRequest, 'StoreCreatedV1'],
+        [ReceiveProductEventRequest, 'InventoryMovementV1'],
+        [ReceiveInventoryEventRequest, 'ProductUpdatedV1'],
+    ])('%p rechaza el eventType %s de otra ruta', async (cls, eventType) => {
+        expect(await propertiesWithErrors(cls, { ...base, eventType })).toEqual(['eventType']);
+    });
+
+    describe('eventId', () => {
+        const valid = { ...base, eventType: 'StoreCreatedV1' };
+
+        it('acepta 1024 caracteres', async () => {
+            expect(await propertiesWithErrors(ReceiveStoreEventRequest, { ...valid, eventId: 'e'.repeat(1024) })).toEqual([]);
+        });
+
+        it.each([
+            ['ausente', undefined],
+            ['vacío', ''],
+            ['solo espacios', '   '],
+            ['número', 123],
+            ['1025 caracteres', 'e'.repeat(1025)],
+        ])('rechaza %s', async (_label, eventId) => {
+            expect(await propertiesWithErrors(ReceiveStoreEventRequest, { ...valid, eventId })).toEqual(['eventId']);
+        });
+    });
+
+    describe('occurredAt', () => {
+        const valid = { ...base, eventType: 'StoreCreatedV1' };
+
+        it.each([
+            ['sin zona', '2026-08-01T15:00:00'],
+            ['ausente', undefined],
+            ['texto', 'hoy'],
+        ])('rechaza %s', async (_label, occurredAt) => {
+            expect(await propertiesWithErrors(ReceiveStoreEventRequest, { ...valid, occurredAt })).toEqual(['occurredAt']);
+        });
+
+        it('acepta un offset', async () => {
+            expect(await propertiesWithErrors(ReceiveStoreEventRequest, { ...valid, occurredAt: '2026-08-01T09:00:00-06:00' })).toEqual([]);
+        });
+    });
+
+    describe('payload', () => {
+        const valid = { ...base, eventType: 'StoreCreatedV1' };
+
+        it.each([
+            ['ausente', undefined],
+            ['null', null],
+            ['arreglo', [1, 2]],
+            ['string', 'tienda'],
+        ])('rechaza %s', async (_label, payload) => {
+            expect(await propertiesWithErrors(ReceiveStoreEventRequest, { ...valid, payload })).toEqual(['payload']);
+        });
+
+        it('no valida el contenido del payload', async () => {
+            expect(await propertiesWithErrors(ReceiveStoreEventRequest, { ...valid, payload: { cualquierCosa: [1, { x: null }] } })).toEqual([]);
+        });
+    });
+
+    it('reporta todos los campos que faltan en un sobre vacío', async () => {
+        expect((await propertiesWithErrors(ReceiveStoreEventRequest, {})).sort()).toEqual(['eventId', 'eventType', 'occurredAt', 'payload']);
+    });
+});

package/_test_/unit/retailIntegration/retailOutboundRequests.test.ts

@@ -0,0 +1,69 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+    GetRetailInventoryRequest,
+    ListRetailCatalogRequest,
+    ListRetailStoresRequest,
+    ListRetailUsersRequest,
+    RegisterRetailSaleRequest,
+} from '../../../src/retailIntegration';
+import { RetailIntegration } from '../../../src';
+
+async function propertiesWithErrors(cls: new () => object, plain: Record<string, unknown>): Promise<string[]> {
+    const errors = await validate(plainToInstance(cls, plain));
+    return errors.map((error) => error.property);
+}
+
+describe('DTOs de salida hacia el retailer', () => {
+    describe.each([ListRetailStoresRequest, ListRetailCatalogRequest, ListRetailUsersRequest])('%p (paginada)', (cls) => {
+        it('acepta solo tenantId', async () => {
+            expect(await propertiesWithErrors(cls, { tenantId: 'surekeep' })).toEqual([]);
+        });
+
+        it('convierte limit de string a número', async () => {
+            const dto = plainToInstance(cls, { tenantId: 'surekeep', limit: '50' }) as { limit?: number };
+            expect(dto.limit).toBe(50);
+            expect(await validate(dto)).toEqual([]);
+        });
+
+        it.each(['0', '201', 'abc', '1.5', ''])('rechaza limit=%p', async (limit) => {
+            expect(await propertiesWithErrors(cls, { tenantId: 'surekeep', limit })).toEqual(['limit']);
+        });
+
+        it('acepta nextToken opaco y rechaza nextToken vacío', async () => {
+            expect(await propertiesWithErrors(cls, { tenantId: 'surekeep', nextToken: 'eyJpZCI6MTQwMH0' })).toEqual([]);
+            expect(await propertiesWithErrors(cls, { tenantId: 'surekeep', nextToken: '' })).toEqual(['nextToken']);
+        });
+    });
+
+    it.each([
+        ['ausente', undefined],
+        ['con diagonal', 'sure/keep'],
+        ['vacío', ''],
+    ])('rechaza tenantId %s', async (_label, tenantId) => {
+        expect(await propertiesWithErrors(ListRetailStoresRequest, { tenantId })).toEqual(['tenantId']);
+    });
+
+    it('inventario exige storeId', async () => {
+        expect(await propertiesWithErrors(GetRetailInventoryRequest, { tenantId: 'surekeep', storeId: '12' })).toEqual([]);
+        expect(await propertiesWithErrors(GetRetailInventoryRequest, { tenantId: 'surekeep' })).toEqual(['storeId']);
+        expect(await propertiesWithErrors(GetRetailInventoryRequest, { tenantId: 'surekeep', storeId: '  ' })).toEqual(['storeId']);
+    });
+
+    it('usuarios acepta storeId opcional', async () => {
+        expect(await propertiesWithErrors(ListRetailUsersRequest, { tenantId: 'surekeep', storeId: '12' })).toEqual([]);
+        expect(await propertiesWithErrors(ListRetailUsersRequest, { tenantId: 'surekeep', storeId: '' })).toEqual(['storeId']);
+    });
+
+    it('venta solo valida tenantId', async () => {
+        expect(await propertiesWithErrors(RegisterRetailSaleRequest, { tenantId: 'surekeep' })).toEqual([]);
+        expect(await propertiesWithErrors(RegisterRetailSaleRequest, {})).toEqual(['tenantId']);
+    });
+
+    it('el módulo se expone en la raíz como RetailIntegration', () => {
+        expect(RetailIntegration.ListRetailStoresRequest).toBe(ListRetailStoresRequest);
+        expect(RetailIntegration.ReceiveStoreEventRequest).toBeDefined();
+        expect(RetailIntegration.RetailEventResultEnum.APPLIED).toBe('APPLIED');
+    });
+});