@fiado/type-kit 3.577.0 → 3.579.0

package/_test_/unit/platformRbac/dtos/levelEntityAdminDtos.test.ts

@@ -58,3 +58,17 @@ describe('DeleteLevelEntityRequest', () => {
         expect(errors.some(e => e.property === 'actedBy')).toBe(true);
     });
 });
+
+describe('UpdateLevelEntityRequest con parentId', () => {
+    it('acepta parentId para mover el grupo de padre', async () => {
+        const dto = plainToInstance(UpdateLevelEntityRequest, { parentId: 'zona-2', actedBy: 'admin-sub-1' });
+        expect(await validate(dto)).toEqual([]);
+        expect(dto.parentId).toBe('zona-2');
+    });
+
+    it('rechaza parentId vacío', async () => {
+        const dto = plainToInstance(UpdateLevelEntityRequest, { parentId: '', actedBy: 'admin-sub-1' });
+        const errors = await validate(dto);
+        expect(errors.some(e => e.property === 'parentId')).toBe(true);
+    });
+});

package/_test_/unit/retailCatalog/catalogEnums.test.ts

@@ -39,9 +39,9 @@ describe('retailCatalog — enums de la operación independiente', () => {
     expect(Object.values(RetailCatalog.ItemTypeEnum)).toEqual(['PRODUCT', 'SERVICE']);
   });
 
-  it('agrega IN_TRANSIT y HELD al estado de pieza sin quitar los existentes', () => {
+  it('agrega IN_TRANSIT, HELD e INACTIVE al estado de pieza sin quitar los existentes', () => {
     expect(Object.values(RetailCatalog.InventoryItemStatusEnum)).toEqual([
-      'AVAILABLE', 'RESERVED', 'SOLD', 'RETURNED', 'DAMAGED', 'IN_TRANSIT', 'HELD',
+      'AVAILABLE', 'RESERVED', 'SOLD', 'RETURNED', 'DAMAGED', 'IN_TRANSIT', 'HELD', 'INACTIVE',
     ]);
   });
 

package/_test_/unit/retailCatalog/centralSaleAccepted.test.ts

@@ -0,0 +1,54 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import {
+  InventoryCentralSaleAcceptedMessage,
+  type InventoryInboundMessage,
+  InventoryInboundMessageTypeEnum,
+} from '../../../src/retailCatalog';
+
+const line = { lineId: 'L1', sku: 'ACC-1', qty: 1, components: [{ sku: 'ACC-1', qty: 1, identifiers: [] }] };
+const valid = {
+  type: 'CENTRAL_SALE_ACCEPTED',
+  tenantId: 'tenant-1',
+  retailerId: 'ret-1',
+  storeId: 'store-1',
+  saleId: 'sale-1',
+  lines: [line],
+  acceptedAt: '2026-10-25T10:00:00.000Z',
+};
+
+function propsWithErrors(payload: object): string[] {
+  return validateSync(plainToInstance(InventoryCentralSaleAcceptedMessage, payload)).map((e) => e.property);
+}
+
+describe('InventoryCentralSaleAcceptedMessage', () => {
+  it('el enum trae CENTRAL_SALE_ACCEPTED sin perder los tipos previos', () => {
+    expect(InventoryInboundMessageTypeEnum.CENTRAL_SALE_ACCEPTED).toBe('CENTRAL_SALE_ACCEPTED');
+    expect(InventoryInboundMessageTypeEnum.SALE_APPLIED).toBe('SALE_APPLIED');
+    expect(InventoryInboundMessageTypeEnum.RETURN).toBe('RETURN');
+  });
+
+  it('acepta el mensaje completo', () => {
+    expect(propsWithErrors(valid)).toEqual([]);
+  });
+
+  it.each(['tenantId', 'retailerId', 'storeId', 'saleId', 'lines', 'acceptedAt'])('rechaza sin %s', (field) => {
+    const payload: Record<string, unknown> = { ...valid };
+    delete payload[field];
+    expect(propsWithErrors(payload)).toContain(field);
+  });
+
+  it('rechaza otro type', () => {
+    expect(propsWithErrors({ ...valid, type: 'RETURN' })).toContain('type');
+  });
+
+  it('rechaza una línea mal formada', () => {
+    expect(propsWithErrors({ ...valid, lines: [{ lineId: 'L1' }] })).toContain('lines');
+  });
+
+  it('forma parte de la unión de la cola', () => {
+    const message: InventoryInboundMessage = plainToInstance(InventoryCentralSaleAcceptedMessage, valid);
+    expect(message.type).toBe(InventoryInboundMessageTypeEnum.CENTRAL_SALE_ACCEPTED);
+  });
+});

package/_test_/unit/retailCatalog/sellInventoryRequest.test.ts

@@ -0,0 +1,25 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import { SellInventoryRequest } from '../../../src/retailCatalog';
+import { RetailCatalog } from '../../../src';
+
+function errorsOf(payload: object): string[] {
+  return validateSync(plainToInstance(SellInventoryRequest, payload)).map((e) => e.property);
+}
+
+describe('SellInventoryRequest (PUT /private/inventory/{imei}/sell)', () => {
+  const ok = { sessionId: 's-1', customerId: 'c-1', saleId: 'sale-1' };
+
+  it('acepta sesión, comprador y venta', () => expect(errorsOf(ok)).toEqual([]));
+
+  it.each([undefined, '', 123])('exige saleId no vacío (%p)', (saleId) => {
+    expect(errorsOf({ ...ok, saleId })).toEqual(['saleId']);
+  });
+
+  it('exige sessionId y customerId', () => {
+    expect(errorsOf({ saleId: 'sale-1' }).sort()).toEqual(['customerId', 'sessionId']);
+  });
+
+  it('se expone en la raíz', () => expect(RetailCatalog.SellInventoryRequest).toBe(SellInventoryRequest));
+});

package/_test_/unit/retailCatalog/stockRequests.test.ts

@@ -62,15 +62,16 @@ describe('SuggestPiecesQuery', () => {
 
 describe('SellStockRequest y ReturnStockRequest', () => {
   it('acepta una venta con componentes e identificadores', () => {
-    expect(errorsOf(SellStockRequest, { sessionId: 's', retailerId: 'ret', lines: [saleLine] })).toEqual([]);
+    expect(errorsOf(SellStockRequest, { sessionId: 's', saleId: 'sale-1', retailerId: 'ret', lines: [saleLine] })).toEqual([]);
   });
   it('valida los identificadores del componente', () => {
     const bad = { ...saleLine, components: [{ sku: 'SIM-1', qty: 1, identifiers: [123] }] };
-    expect(errorsOf(SellStockRequest, { sessionId: 's', retailerId: 'ret', lines: [bad] })).toContain('lines.0.components.0.identifiers');
+    expect(errorsOf(SellStockRequest, { sessionId: 's', saleId: 'sale-1', retailerId: 'ret', lines: [bad] })).toContain('lines.0.components.0.identifiers');
   });
-  it('acepta saleId opcional', () => {
+  it('exige saleId no vacío en la venta', () => {
     const base = { sessionId: 's', retailerId: 'ret', lines: [saleLine] };
-    expect(errorsOf(SellStockRequest, { ...base, saleId: 'sale-1' })).toEqual([]);
+    expect(errorsOf(SellStockRequest, base)).toContain('saleId');
+    expect(errorsOf(SellStockRequest, { ...base, saleId: '' })).toContain('saleId');
     expect(errorsOf(SellStockRequest, { ...base, saleId: 123 })).toContain('saleId');
   });
   it('devolución exige saleId y soldAt ISO', () => {
@@ -78,6 +79,15 @@ describe('SellStockRequest y ReturnStockRequest', () => {
     expect(errorsOf(ReturnStockRequest, ok)).toEqual([]);
     expect(errorsOf(ReturnStockRequest, { ...ok, soldAt: 'ayer' })).toContain('soldAt');
   });
+  it('devolución acepta centralCancelFirstAttemptAt ISO opcional', () => {
+    const ok = { saleId: 'sale', retailerId: 'ret', soldAt: '2026-09-23T10:00:00.000Z', lines: [saleLine] };
+    expect(errorsOf(ReturnStockRequest, { ...ok, centralCancelFirstAttemptAt: '2026-09-24T10:00:00.000Z' })).toEqual([]);
+    expect(errorsOf(ReturnStockRequest, { ...ok, centralCancelFirstAttemptAt: 'ayer' })).toContain('centralCancelFirstAttemptAt');
+  });
+  it('devolución con centralCancelFirstAttemptAt no ISO falla solo en ese campo', () => {
+    const ok = { saleId: 'sale', retailerId: 'ret', soldAt: '2026-09-23T10:00:00.000Z', lines: [saleLine] };
+    expect(errorsOf(ReturnStockRequest, { ...ok, centralCancelFirstAttemptAt: 'ayer' })).toEqual(['centralCancelFirstAttemptAt']);
+  });
 });
 
 describe('SyncInventoryRequest', () => {

package/_test_/unit/retailCatalog/ventaSaga.test.ts

@@ -123,6 +123,13 @@ describe('InventoryReturnMessage', () => {
   it('valida las líneas como ReturnStockRequest', () => {
     expect(errorsOf(InventoryReturnMessage, { ...ok, lines: [] })).toContain('lines');
   });
+  it('acepta el RETURN de hoy sin centralCancelFirstAttemptAt y con él en ISO', () => {
+    expect(errorsOf(InventoryReturnMessage, ok)).toEqual([]);
+    expect(errorsOf(InventoryReturnMessage, { ...ok, centralCancelFirstAttemptAt: '2026-09-29T09:00:00.000Z' })).toEqual([]);
+  });
+  it('rechaza centralCancelFirstAttemptAt que no es ISO', () => {
+    expect(errorsOf(InventoryReturnMessage, { ...ok, centralCancelFirstAttemptAt: 'hoy' })).toContain('centralCancelFirstAttemptAt');
+  });
 });
 
 describe('ReserveStockRequest.purpose', () => {

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

@@ -0,0 +1,121 @@
+import 'reflect-metadata';
+import { plainToInstance, type ClassConstructor } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import {
+  type GetCatalogReconciliationResponse,
+  type GetOrgReconciliationResponse,
+  InactiveReasonEnum,
+  ReconciliationEntityEnum,
+  ReconciliationPageMessage,
+  ReconciliationRunStatusEnum,
+  ReconciliationTriggerEnum,
+  StartCatalogReconciliationRequest,
+  type StartCatalogReconciliationResponse,
+  StartOrgReconciliationRequest,
+  type StartOrgReconciliationResponse,
+} from '../../../src/retailIntegration';
+
+function propsWithErrors<T extends object>(cls: ClassConstructor<T>, payload: object): string[] {
+  return validateSync(plainToInstance(cls, payload)).map((e) => e.property);
+}
+
+describe('enums de la revisión', () => {
+  it('ReconciliationEntityEnum trae las cuatro entidades', () => {
+    expect(Object.values(ReconciliationEntityEnum)).toEqual(['STORES', 'USERS', 'CATALOG', 'INVENTORY']);
+  });
+
+  it('ReconciliationRunStatusEnum trae los cuatro estados de la corrida', () => {
+    expect(Object.values(ReconciliationRunStatusEnum)).toEqual(['RUNNING', 'COMPLETE', 'ABORTED', 'BRAKED']);
+  });
+
+  it('ReconciliationTriggerEnum distingue el reloj del botón', () => {
+    expect(Object.values(ReconciliationTriggerEnum)).toEqual(['SCHEDULED', 'MANUAL', 'ACTIVATION']);
+  });
+
+  it('InactiveReasonEnum distingue la baja de la revisión de la del evento', () => {
+    expect(Object.values(InactiveReasonEnum)).toEqual(['NOT_IN_ZENTRAL', 'ZENTRAL_EVENT']);
+  });
+});
+
+describe('StartOrgReconciliationRequest', () => {
+  it.each(['STORES', 'USERS'])('acepta %s', (entity) => {
+    expect(propsWithErrors(StartOrgReconciliationRequest, { entity })).toEqual([]);
+  });
+
+  it.each(['CATALOG', 'INVENTORY', 'OTRA', undefined])('rechaza %s', (entity) => {
+    expect(propsWithErrors(StartOrgReconciliationRequest, { entity })).toContain('entity');
+  });
+});
+
+describe('StartCatalogReconciliationRequest', () => {
+  it('acepta CATALOG sin tienda', () => {
+    expect(propsWithErrors(StartCatalogReconciliationRequest, { entity: 'CATALOG' })).toEqual([]);
+  });
+
+  it('acepta INVENTORY con y sin tienda', () => {
+    expect(propsWithErrors(StartCatalogReconciliationRequest, { entity: 'INVENTORY' })).toEqual([]);
+    expect(propsWithErrors(StartCatalogReconciliationRequest, { entity: 'INVENTORY', storeId: 's-1' })).toEqual([]);
+  });
+
+  it.each(['STORES', 'USERS', undefined])('rechaza %s', (entity) => {
+    expect(propsWithErrors(StartCatalogReconciliationRequest, { entity })).toContain('entity');
+  });
+
+  it('rechaza storeId vacío', () => {
+    expect(propsWithErrors(StartCatalogReconciliationRequest, { entity: 'INVENTORY', storeId: '' })).toContain('storeId');
+  });
+});
+
+describe('ReconciliationPageMessage', () => {
+  const valid = { tenantId: 't-1', retailerId: 'r-1', entity: 'STORES', runId: 'run-1', pageIndex: 0 };
+
+  it('acepta la página 1 y la página de una tienda de inventario', () => {
+    expect(propsWithErrors(ReconciliationPageMessage, valid)).toEqual([]);
+    expect(propsWithErrors(ReconciliationPageMessage, { ...valid, entity: 'INVENTORY', storeId: 's-1' })).toEqual([]);
+  });
+
+  it.each(['tenantId', 'retailerId', 'entity', 'runId', 'pageIndex'])('rechaza sin %s', (field) => {
+    const payload: Record<string, unknown> = { ...valid };
+    delete payload[field];
+    expect(propsWithErrors(ReconciliationPageMessage, payload)).toContain(field);
+  });
+
+  it('rechaza un índice negativo o fraccionario', () => {
+    expect(propsWithErrors(ReconciliationPageMessage, { ...valid, pageIndex: -1 })).toContain('pageIndex');
+    expect(propsWithErrors(ReconciliationPageMessage, { ...valid, pageIndex: 1.5 })).toContain('pageIndex');
+  });
+});
+
+describe('respuestas de la revisión', () => {
+  it('el 202 lleva el runId y el GET el avance, los conteos y el estado', () => {
+    const startOrg: StartOrgReconciliationResponse = { runId: 'run-1' };
+    const startCatalog: StartCatalogReconciliationResponse = { runId: 'run-2' };
+    const counts = { seen: 10, created: 1, updated: 2, deactivated: 0, reactivated: 1, skipped: 0 };
+    const org: GetOrgReconciliationResponse = {
+      runId: startOrg.runId,
+      retailerId: 'r-1',
+      entity: ReconciliationEntityEnum.USERS,
+      status: ReconciliationRunStatusEnum.RUNNING,
+      trigger: ReconciliationTriggerEnum.MANUAL,
+      triggeredBy: 'sub-1',
+      startedAt: '2026-10-25T10:00:00.000Z',
+      pagesProcessed: 2,
+      counts,
+    };
+    const catalog: GetCatalogReconciliationResponse = {
+      runId: startCatalog.runId,
+      retailerId: 'r-1',
+      entity: ReconciliationEntityEnum.INVENTORY,
+      status: ReconciliationRunStatusEnum.COMPLETE,
+      trigger: ReconciliationTriggerEnum.SCHEDULED,
+      startedAt: '2026-10-25T10:00:00.000Z',
+      finishedAt: '2026-10-25T10:05:00.000Z',
+      pagesProcessed: 4,
+      storeId: 's-1',
+      storesPending: 0,
+      counts,
+    };
+    expect(org.counts.seen).toBe(10);
+    expect(catalog.storesPending).toBe(0);
+  });
+});

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

@@ -0,0 +1,37 @@
+import 'reflect-metadata';
+import {
+    RETAIL_INTEGRATION_ERROR_HTTP_STATUS,
+    RetailEventRejectCodeEnum,
+    RetailIntegrationErrorCodeEnum as C,
+} from '../../../src/retailIntegration/index';
+
+describe('RetailEventRejectCodeEnum', () => {
+    it('incluye EVENT_IN_FUTURE y no RETAILER_NOT_INTEGRATED', () => {
+        expect(RetailEventRejectCodeEnum.EVENT_IN_FUTURE).toBe('EVENT_IN_FUTURE');
+        expect(Object.values(RetailEventRejectCodeEnum)).not.toContain('RETAILER_NOT_INTEGRATED');
+    });
+});
+
+describe('RetailIntegrationErrorCodeEnum', () => {
+    it.each([
+        [C.ENTITY_MANAGED_BY_INTEGRATION, 422],
+        [C.RECONCILIATION_ALREADY_RUNNING, 409],
+        [C.RECONCILIATION_NOT_FOUND, 404],
+        [C.RESERVATION_LOST, 409],
+        [C.PRODUCT_NO_LONGER_SELLABLE, 409],
+        [C.STORE_NOT_OPERATIONAL, 422],
+        [C.CENTRAL_SYNC_NOT_RESENDABLE, 409],
+        [C.SALE_NOT_FOUND, 404],
+        [C.RETAILER_ALREADY_INTEGRATED, 409],
+        [C.RETAILER_NOT_INTEGRATED, 422],
+        [C.CREDIT_REQUIRES_MDM, 422],
+        [C.RETAILER_INTEGRATION_MISMATCH, 422],
+    ])('%s → %i', (code, status) => {
+        expect(RETAIL_INTEGRATION_ERROR_HTTP_STATUS[code]).toBe(status);
+    });
+
+    it('cada valor es igual a su llave y son exactamente 12', () => {
+        for (const [key, value] of Object.entries(C)) expect(value).toBe(key);
+        expect(Object.keys(C)).toHaveLength(12);
+    });
+});

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

@@ -6,10 +6,13 @@ import {
     ListRetailCatalogRequest,
     ListRetailStoresRequest,
     ListRetailUsersRequest,
+    CheckRetailInventoryRequest,
     RegisterRetailSaleRequest,
 } from '../../../src/retailIntegration';
 import { RetailIntegration } from '../../../src';
 
+const tenant = { tenantId: 'surekeep', retailerId: 'ret-1' };
+
 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);
@@ -17,23 +20,23 @@ async function propertiesWithErrors(cls: new () => object, plain: Record<string,
 
 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('acepta solo tenantId y retailerId', async () => {
+            expect(await propertiesWithErrors(cls, { ...tenant })).toEqual([]);
         });
 
         it('convierte limit de string a número', async () => {
-            const dto = plainToInstance(cls, { tenantId: 'surekeep', limit: '50' }) as { limit?: number };
+            const dto = plainToInstance(cls, { ...tenant, 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']);
+            expect(await propertiesWithErrors(cls, { ...tenant, 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']);
+            expect(await propertiesWithErrors(cls, { ...tenant, nextToken: 'eyJpZCI6MTQwMH0' })).toEqual([]);
+            expect(await propertiesWithErrors(cls, { ...tenant, nextToken: '' })).toEqual(['nextToken']);
         });
     });
 
@@ -42,23 +45,51 @@ describe('DTOs de salida hacia el retailer', () => {
         ['con diagonal', 'sure/keep'],
         ['vacío', ''],
     ])('rechaza tenantId %s', async (_label, tenantId) => {
-        expect(await propertiesWithErrors(ListRetailStoresRequest, { tenantId })).toEqual(['tenantId']);
+        expect(await propertiesWithErrors(ListRetailStoresRequest, { retailerId: 'ret-1', 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']);
+        expect(await propertiesWithErrors(GetRetailInventoryRequest, { ...tenant, storeId: '12' })).toEqual([]);
+        expect(await propertiesWithErrors(GetRetailInventoryRequest, { ...tenant })).toEqual(['storeId']);
+        expect(await propertiesWithErrors(GetRetailInventoryRequest, { ...tenant, 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']);
+        expect(await propertiesWithErrors(ListRetailUsersRequest, { ...tenant, storeId: '12' })).toEqual([]);
+        expect(await propertiesWithErrors(ListRetailUsersRequest, { ...tenant, storeId: '' })).toEqual(['storeId']);
+    });
+
+    it.each([
+        ['ausente', undefined],
+        ['vacío', ''],
+        ['en blanco', '  '],
+        ['no string', 12],
+    ])('toda ruta privada rechaza retailerId %s', async (_label, retailerId) => {
+        const live = { storeId: '12', identifiers: 'A1', sessionId: 's-1' };
+        for (const [cls, extra] of [
+            [ListRetailStoresRequest, {}],
+            [GetRetailInventoryRequest, { storeId: '12' }],
+            [RegisterRetailSaleRequest, {}],
+            [CheckRetailInventoryRequest, live],
+        ] as const) {
+            expect(await propertiesWithErrors(cls, { tenantId: 'surekeep', retailerId, ...extra })).toEqual(['retailerId']);
+        }
+    });
+
+    describe.each([ListRetailStoresRequest, ListRetailCatalogRequest, ListRetailUsersRequest, GetRetailInventoryRequest])('%p (listado)', (cls) => {
+        const base = { ...tenant, storeId: '12' };
+        it('acepta runId opcional', async () => {
+            expect(await propertiesWithErrors(cls, base)).toEqual([]);
+            expect(await propertiesWithErrors(cls, { ...base, runId: 'run-1' })).toEqual([]);
+        });
+        it.each(['', '  ', 7])('rechaza runId=%p', async (runId) => {
+            expect(await propertiesWithErrors(cls, { ...base, runId })).toEqual(['runId']);
+        });
     });
 
-    it('venta solo valida tenantId', async () => {
-        expect(await propertiesWithErrors(RegisterRetailSaleRequest, { tenantId: 'surekeep' })).toEqual([]);
-        expect(await propertiesWithErrors(RegisterRetailSaleRequest, {})).toEqual(['tenantId']);
+    it('venta solo valida tenantId y retailerId', async () => {
+        expect(await propertiesWithErrors(RegisterRetailSaleRequest, { ...tenant })).toEqual([]);
+        expect(await propertiesWithErrors(RegisterRetailSaleRequest, {})).toEqual(['tenantId', 'retailerId']);
     });
 
     it('el módulo se expone en la raíz como RetailIntegration', () => {

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

@@ -0,0 +1,160 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate, ValidationError } from 'class-validator';
+import {
+    CancelRetailSaleRequest,
+    CancelRetailSaleResponse,
+    CheckRetailInventoryRequest,
+    CheckRetailInventoryResponse,
+    RETAIL_LIVE_CHECK_IDENTIFIERS_MAX,
+    RetailSaleLineRoleEnum,
+    RetailSystemSale,
+    RetailSystemSaleLine,
+} from '../../../src/retailIntegration';
+
+function paths(errors: ValidationError[], prefix = ''): string[] {
+    return errors.flatMap((e) => {
+        const p = prefix ? `${prefix}.${e.property}` : e.property;
+        return e.children && e.children.length > 0 ? paths(e.children, p) : [p];
+    });
+}
+
+async function errorsOf(cls: new () => object, plain: object): Promise<string[]> {
+    return paths(await validate(plainToInstance(cls, plain)));
+}
+
+// Literal tipado: prueba en compilación que la clase sigue aceptando objetos planos.
+const sale: RetailSystemSale = {
+    saleId: '7f0c2a52-1b7e-4f0e-9d7a-2a1d3c4b5e6f',
+    folio: 'SK-000123',
+    storeId: '12',
+    sellerRetailUserId: '431',
+    soldAt: '2026-10-25T18:30:00Z',
+    saleType: 'CREDIT',
+    financier: 'SUREKEEP',
+    creditId: 'CR-991',
+    currencyId: 'MXN',
+    customer: { customerId: 'C-1', names: 'Ana', paternalLastName: 'López', maternalLastName: null, phone: '7221234567' },
+    equipmentPrice: '5999.00',
+    amountPaid: '600.00',
+    paymentMethod: 'CASH',
+    lines: [
+        {
+            lineId: 'L1', sku: 'IPH-15', qty: 1, basePrice: '5999.00', discount: '0.00', paymentType: 'CREDIT',
+            financedAmount: '5399.00', role: null, components: [{ sku: 'IPH-15', qty: 1, identifiers: ['356789012345678'] }],
+        },
+        {
+            lineId: 'L2', sku: 'FUNDA-1', qty: 1, basePrice: '0.00', discount: '0.00', paymentType: 'CASH',
+            financedAmount: '0.00', role: 'GIFT', components: [],
+        },
+    ],
+};
+
+describe('RetailSystemSale (body de privateRegisterRetailSale)', () => {
+    it('acepta una venta completa', async () => {
+        expect(await errorsOf(RetailSystemSale, sale)).toEqual([]);
+    });
+
+    it('acepta los nullables en null', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, creditId: null, paymentMethod: null })).toEqual([]);
+    });
+
+    it.each([
+        ['saleId', { saleId: '' }],
+        ['storeId', { storeId: 'a/b' }],
+        ['soldAt', { soldAt: '2026-10-25T18:30:00' }],
+        ['saleType', { saleType: 'BARTER' }],
+        ['financier', { financier: 'OTRO' }],
+        ['currencyId', { currencyId: 'EUR' }],
+        ['equipmentPrice', { equipmentPrice: '5999' }],
+        ['amountPaid', { amountPaid: '-1.00' }],
+        ['paymentMethod', { paymentMethod: 'BITCOIN' }],
+        ['creditId', { creditId: undefined }],
+        ['lines', { lines: [] }],
+    ])('rechaza %s inválido', async (field, patch) => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, ...patch })).toEqual([field]);
+    });
+
+    it('valida el cliente anidado', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, customer: { ...sale.customer, names: '' } })).toEqual(['customer.names']);
+    });
+
+    it('valida las líneas y sus componentes', async () => {
+        const [line] = sale.lines;
+        const lines = [{ ...line, qty: 0, role: 'PROMO', components: [{ sku: 'IPH-15', qty: 1, identifiers: [''] }] }];
+        expect(await errorsOf(RetailSystemSale, { ...sale, lines })).toEqual(['lines.0.qty', 'lines.0.role', 'lines.0.components.0.identifiers']);
+    });
+
+    it('rechaza lineId repetido', async () => {
+        expect(await errorsOf(RetailSystemSale, { ...sale, lines: [sale.lines[0], sale.lines[0]] })).toEqual(['lines']);
+    });
+});
+
+describe('CancelRetailSaleRequest', () => {
+    const cancel = { saleId: sale.saleId, cancelledAt: '2026-10-25T19:00:00-06:00', reason: 'Cliente desistió' };
+
+    it('acepta la cancelación', async () => {
+        expect(await errorsOf(CancelRetailSaleRequest, cancel)).toEqual([]);
+    });
+
+    it.each([
+        ['saleId', { saleId: ' ' }],
+        ['cancelledAt', { cancelledAt: '2026-02-31T10:00:00Z' }],
+        ['reason', { reason: '' }],
+        ['reason', { reason: undefined }],
+    ])('rechaza %s inválido', async (field, patch) => {
+        expect(await errorsOf(CancelRetailSaleRequest, { ...cancel, ...patch })).toEqual([field]);
+    });
+
+    it('la respuesta trae el saleId', () => {
+        const response: CancelRetailSaleResponse = { saleId: cancel.saleId };
+        expect(response.saleId).toBe(cancel.saleId);
+    });
+});
+
+describe('RetailSaleLineRoleEnum', () => {
+    it('serializa GIFT y el rol acepta el literal o el miembro del enum', () => {
+        const fromLiteral: RetailSystemSaleLine['role'] = 'GIFT';
+        const fromEnum: RetailSystemSaleLine['role'] = RetailSaleLineRoleEnum.GIFT;
+        expect(Object.values(RetailSaleLineRoleEnum)).toEqual(['GIFT']);
+        expect(fromLiteral).toBe(fromEnum);
+    });
+});
+
+describe('CheckRetailInventoryRequest (query de privateCheckRetailInventory)', () => {
+    const query = { tenantId: 'surekeep', retailerId: 'ret-1', storeId: '12', identifiers: '356789012345678, SN-ABC', sessionId: 'sess-1' };
+
+    it('acepta hasta el tope de identificadores y rechaza uno más', async () => {
+        const many = (n: number) => Array.from({ length: n }, (_, i) => `SN-${i}`);
+        expect(RETAIL_LIVE_CHECK_IDENTIFIERS_MAX).toBe(50);
+        expect(await errorsOf(CheckRetailInventoryRequest, { ...query, identifiers: many(RETAIL_LIVE_CHECK_IDENTIFIERS_MAX) })).toEqual([]);
+        expect(await errorsOf(CheckRetailInventoryRequest, { ...query, identifiers: many(RETAIL_LIVE_CHECK_IDENTIFIERS_MAX + 1).join(',') })).toEqual(['identifiers']);
+    });
+
+    it('convierte identifiers de csv a arreglo sin espacios', async () => {
+        const dto = plainToInstance(CheckRetailInventoryRequest, query);
+        expect(dto.identifiers).toEqual(['356789012345678', 'SN-ABC']);
+        expect(await validate(dto)).toEqual([]);
+    });
+
+    it('acepta identifiers ya como arreglo', async () => {
+        expect(await errorsOf(CheckRetailInventoryRequest, { ...query, identifiers: ['356789012345678'] })).toEqual([]);
+    });
+
+    it.each([
+        ['identifiers', { identifiers: '' }],
+        ['identifiers', { identifiers: 'A,,B' }],
+        ['identifiers', { identifiers: undefined }],
+        ['storeId', { storeId: undefined }],
+        ['sessionId', { sessionId: '' }],
+        ['tenantId', { tenantId: 'sure/keep' }],
+        ['retailerId', { retailerId: '' }],
+    ])('rechaza %s inválido', async (field, patch) => {
+        expect(await errorsOf(CheckRetailInventoryRequest, { ...query, ...patch })).toEqual([field]);
+    });
+
+    it('la respuesta lista identificadores y la fecha de Zentral', () => {
+        const response: CheckRetailInventoryResponse = { listed: ['356789012345678'], generatedAt: '2026-10-25T18:30:00Z' };
+        expect(response.listed).toHaveLength(1);
+    });
+});

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

@@ -46,7 +46,7 @@ describe('codes y movimientos de los eventos del retailer', () => {
     it('un solo enum de REJECTED para los 4 endpoints', () => {
         expect(Object.values(RetailEventRejectCodeEnum).sort()).toEqual(
             [
-                'EMAIL_ALREADY_IN_USE', 'FUTURE_PRICE_NOT_SUPPORTED', 'IDENTIFIER_CONFLICT', 'INVALID_IMEI',
+                'EMAIL_ALREADY_IN_USE', 'EVENT_IN_FUTURE', 'FUTURE_PRICE_NOT_SUPPORTED', 'IDENTIFIER_CONFLICT', 'INVALID_IMEI',
                 'INVALID_PAYLOAD', 'RETAIL_USER_RETAILER_MISMATCH', 'SKU_NOT_STOCKABLE', 'SKU_OWNED_BY_BACKOFFICE',
                 'STORE_CODE_TAKEN', 'STORE_NOT_IN_RETAILER', 'STORE_RETAILER_MISMATCH', 'TRACKING_MODE_MISMATCH',
                 'UNSUPPORTED_CURRENCY',