@fiado/type-kit 3.583.0 → 3.585.0

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

@@ -0,0 +1,24 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import { UpdateTenantUserEmailRequest } from '../../../../src/platformRbac';
+
+function propsWithErrors(payload: object): string[] {
+    return validateSync(plainToInstance(UpdateTenantUserEmailRequest, payload)).map((e) => e.property);
+}
+
+describe('UpdateTenantUserEmailRequest', () => {
+    it('normaliza el correo a minúsculas sin espacios', () => {
+        const dto = plainToInstance(UpdateTenantUserEmailRequest, { email: '  Ana.Perez@Example.COM ', actedBy: 'retail-org-business' });
+        expect(dto.email).toBe('ana.perez@example.com');
+        expect(validateSync(dto)).toEqual([]);
+    });
+
+    it.each([undefined, '', 'no-es-correo', 42])('rechaza email=%p', (email) => {
+        expect(propsWithErrors({ email, actedBy: 'retail-org-business' })).toEqual(['email']);
+    });
+
+    it.each([undefined, '', 7])('rechaza actedBy=%p', (actedBy) => {
+        expect(propsWithErrors({ email: 'ana@example.com', actedBy })).toEqual(['actedBy']);
+    });
+});

package/_test_/unit/platformRbac/enums/__snapshots__/permissionBits.test.ts.snap

@@ -1,6 +1,6 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
-exports[`PERMISSION_BIT_ORDER PERMS_VERSION es número estable 1`] = `2686516275`;
+exports[`PERMISSION_BIT_ORDER PERMS_VERSION es número estable 1`] = `1071810597`;
 
 exports[`PERMISSION_BIT_ORDER append-only: snapshot del ORDEN COMPLETO (rompe ante cualquier reorden/inserción) 1`] = `
 [
@@ -96,5 +96,6 @@ exports[`PERMISSION_BIT_ORDER append-only: snapshot del ORDEN COMPLETO (rompe an
   "platform.integration.key.revoke",
   "tenant.integration.diagnostic",
   "tenant.api_user.manage",
+  "platform.retail_integration.activate",
 ]
 `;

package/_test_/unit/platformRbac/enums/apiUserPermission.test.ts

@@ -5,7 +5,8 @@ describe('Permiso de administración de usuarios de API', () => {
         expect(Permission.TENANT_API_USER_MANAGE).toBe('tenant.api_user.manage');
     });
 
-    it('va al FINAL del orden de bits (append-only)', () => {
-        expect(PERMISSION_BIT_ORDER[PERMISSION_BIT_ORDER.length - 1]).toBe(Permission.TENANT_API_USER_MANAGE);
+    it('conserva su bit después de las integraciones M2M (append-only)', () => {
+        const index = PERMISSION_BIT_ORDER.indexOf(Permission.TENANT_API_USER_MANAGE);
+        expect(PERMISSION_BIT_ORDER[index - 1]).toBe(Permission.TENANT_INTEGRATION_DIAGNOSTIC);
     });
 });

package/_test_/unit/platformRbac/enums/retailIntegrationPermission.test.ts

@@ -0,0 +1,13 @@
+import { Permission, PERMISSION_BIT_ORDER } from '../../../../src/platformRbac/enums/Permission';
+
+describe('Permiso de activación de la integración retail', () => {
+    it('existe con la llave platform.retail_integration.activate (scope PLATFORM)', () => {
+        expect(Permission.PLATFORM_RETAIL_INTEGRATION_ACTIVATE).toBe('platform.retail_integration.activate');
+    });
+
+    it('va al FINAL del orden de bits, justo después de tenant.api_user.manage', () => {
+        const last = PERMISSION_BIT_ORDER.length - 1;
+        expect(PERMISSION_BIT_ORDER[last]).toBe(Permission.PLATFORM_RETAIL_INTEGRATION_ACTIVATE);
+        expect(PERMISSION_BIT_ORDER[last - 1]).toBe(Permission.TENANT_API_USER_MANAGE);
+    });
+});

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

@@ -0,0 +1,147 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate, ValidationError } from 'class-validator';
+import { StoreEventPayload } from '../../../src/retailIntegration/dtos/StoreEventPayload';
+import { RetailUserEventPayload } from '../../../src/retailIntegration/dtos/RetailUserEventPayload';
+import { ProductEventPayload } from '../../../src/retailIntegration/dtos/ProductEventPayload';
+import { InventoryEventPayload } from '../../../src/retailIntegration/dtos/InventoryEventPayload';
+import {
+    RETAIL_ELIGIBLE_FINANCIERS_MAX,
+    RETAIL_EVENT_STOCK_MAX,
+    RETAIL_ID_TEXT_MAX_LENGTH,
+    RETAIL_LONG_TEXT_MAX_LENGTH,
+    RETAIL_SHORT_TEXT_MAX_LENGTH,
+} from '../../../src/retailIntegration/constants/retailIntegrationLimits';
+
+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: Record<string, unknown>): Promise<string[]> {
+    return paths(await validate(plainToInstance(cls, plain)));
+}
+
+const text = (n: number): string => 'a'.repeat(n);
+const SHORT = RETAIL_SHORT_TEXT_MAX_LENGTH;
+const LONG = RETAIL_LONG_TEXT_MAX_LENGTH;
+const ID = RETAIL_ID_TEXT_MAX_LENGTH;
+
+const address = { address1: 'Av. Juárez', externalNumber: '120', internalNumber: null, neighborhood: 'Centro', city: 'Toluca', state: 'Estado de México', zipCode: '50000', country: 'MX', reference: null };
+const store = {
+    storeId: '12', code: 'T12', name: 'Sucursal Centro', zoneId: 'SUR', address,
+    location: { lat: 19.2826, lng: -99.6557 }, phone: '7221234567', schedule: 'Lun a Dom 10:00 a 20:00', status: 'ACTIVE',
+};
+const user = {
+    retailUserId: '431', displayName: 'Grecia Cruz Mendoza', email: 'gcruz@ejemplo.mx', phone: null,
+    homeStoreId: '12', zoneId: null, role: 'SELLER', status: 'ACTIVE',
+};
+const price = { basePrice: '4299.00', listPrice: null, effectiveFrom: '2026-08-17T20:32:05Z' };
+const product = {
+    sku: 'SAM-A17-128-NEG', externalId: '9001', brand: 'Samsung', model: 'A17', color: 'Negro', capacity: '128 GB', description: null,
+    category: 'PHONE', trackingMode: 'IMEI', tier: null, currencyId: 'MXN', price,
+    eligibleFinanciers: [], mdmProvider: null, status: 'ACTIVE',
+};
+const piece = { sku: 'SAM-A17-128-NEG', identifier: '356938035643809', storeId: '12', status: 'SOLD', reason: null };
+const movement = { movementType: 'SALE', storeId: '12', targetStoreId: null, pieces: [piece], stock: [] };
+
+describe('StoreEventPayload: topes', () => {
+    it('acepta textos justo en su tope', async () => {
+        const atMax = {
+            ...store, name: text(SHORT), phone: text(SHORT), schedule: text(SHORT),
+            address: { ...address, address1: text(SHORT), externalNumber: text(SHORT), internalNumber: text(SHORT), neighborhood: text(SHORT), city: text(SHORT), state: text(SHORT), country: text(SHORT), reference: text(LONG) },
+        };
+        expect(await errorsOf(StoreEventPayload, atMax)).toEqual([]);
+    });
+
+    it.each([
+        ['name', { name: text(SHORT + 1) }],
+        ['phone', { phone: text(SHORT + 1) }],
+        ['schedule', { schedule: text(SHORT + 1) }],
+        ['address.address1', { address: { ...address, address1: text(SHORT + 1) } }],
+        ['address.externalNumber', { address: { ...address, externalNumber: text(SHORT + 1) } }],
+        ['address.internalNumber', { address: { ...address, internalNumber: text(SHORT + 1) } }],
+        ['address.neighborhood', { address: { ...address, neighborhood: text(SHORT + 1) } }],
+        ['address.city', { address: { ...address, city: text(SHORT + 1) } }],
+        ['address.state', { address: { ...address, state: text(SHORT + 1) } }],
+        ['address.country', { address: { ...address, country: text(SHORT + 1) } }],
+        ['address.reference', { address: { ...address, reference: text(LONG + 1) } }],
+    ])('rechaza %s sobre su tope', async (path, over) => {
+        expect(await errorsOf(StoreEventPayload, { ...store, ...over })).toContain(path);
+    });
+
+    it.each([
+        ['address', 'Av. Juárez 120'],
+        ['address', [address]],
+        ['location', 'lat,lng'],
+        ['location', [19.2, -99.6]],
+    ])('rechaza %s que no es objeto', async (path, value) => {
+        const errors = await validate(plainToInstance(StoreEventPayload, { ...store, [path]: value }));
+        expect(errors.find((e) => e.property === path)?.constraints).toHaveProperty('isObject');
+    });
+});
+
+describe('RetailUserEventPayload: topes', () => {
+    it('acepta textos justo en su tope', async () => {
+        // IsEmail ya topa en 254, uno abajo de RETAIL_SHORT_TEXT_MAX_LENGTH.
+        const email = `${text(64)}@${'b'.repeat(63)}.${'c'.repeat(63)}.${'d'.repeat(58)}.mx`;
+        expect(email).toHaveLength(SHORT - 1);
+        expect(await errorsOf(RetailUserEventPayload, { ...user, displayName: text(SHORT), phone: text(SHORT), email })).toEqual([]);
+    });
+
+    it.each([
+        ['displayName', { displayName: text(SHORT + 1) }],
+        ['phone', { phone: text(SHORT + 1) }],
+        ['email', { email: `${text(SHORT)}@ejemplo.mx` }],
+    ])('rechaza %s sobre su tope', async (path, over) => {
+        expect(await errorsOf(RetailUserEventPayload, { ...user, ...over })).toContain(path);
+    });
+});
+
+describe('ProductEventPayload: topes', () => {
+    it('acepta textos, financieras y montos justo en su tope', async () => {
+        const atMax = {
+            ...product, externalId: text(ID), brand: text(SHORT), model: text(SHORT), color: text(SHORT), capacity: text(SHORT), description: text(LONG),
+            price: { ...price, basePrice: '999999999999.99', listPrice: '999999999999.99' },
+            eligibleFinanciers: Array.from({ length: RETAIL_ELIGIBLE_FINANCIERS_MAX }, () => 'SUREKEEP'),
+        };
+        expect(await errorsOf(ProductEventPayload, atMax)).toEqual([]);
+    });
+
+    it.each([
+        ['externalId', { externalId: text(ID + 1) }],
+        ['brand', { brand: text(SHORT + 1) }],
+        ['model', { model: text(SHORT + 1) }],
+        ['color', { color: text(SHORT + 1) }],
+        ['capacity', { capacity: text(SHORT + 1) }],
+        ['description', { description: text(LONG + 1) }],
+        ['price.basePrice', { price: { ...price, basePrice: '1000000000000.00' } }],
+        ['price.listPrice', { price: { ...price, listPrice: '1000000000000.00' } }],
+        ['eligibleFinanciers', { eligibleFinanciers: Array.from({ length: RETAIL_ELIGIBLE_FINANCIERS_MAX + 1 }, () => 'SUREKEEP') }],
+    ])('rechaza %s', async (path, over) => {
+        expect(await errorsOf(ProductEventPayload, { ...product, ...over })).toContain(path);
+    });
+
+    it.each([['4299.00'], [[price]]])('rechaza price que no es objeto: %j', async (value) => {
+        const errors = await validate(plainToInstance(ProductEventPayload, { ...product, price: value }));
+        expect(errors.find((e) => e.property === 'price')?.constraints).toHaveProperty('isObject');
+    });
+});
+
+describe('InventoryEventPayload: topes', () => {
+    const stockOf = (n: number) => Array.from({ length: n }, (_, i) => ({ sku: `MICA-${String(i)}`, storeId: '12', qty: 1 }));
+
+    it('acepta identifier y stock justo en su tope', async () => {
+        expect(await errorsOf(InventoryEventPayload, { ...movement, pieces: [{ ...piece, identifier: text(SHORT) }], stock: stockOf(RETAIL_EVENT_STOCK_MAX) })).toEqual([]);
+    });
+
+    it('rechaza identifier sobre su tope', async () => {
+        expect(await errorsOf(InventoryEventPayload, { ...movement, pieces: [{ ...piece, identifier: text(SHORT + 1) }] })).toContain('pieces.0.identifier');
+    });
+
+    it('rechaza stock sobre su tope', async () => {
+        expect(await errorsOf(InventoryEventPayload, { ...movement, stock: stockOf(RETAIL_EVENT_STOCK_MAX + 1) })).toContain('stock');
+    });
+});

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

@@ -5,6 +5,7 @@ import { StoreEventPayload } from '../../../src/retailIntegration/dtos/StoreEven
 import { RetailUserEventPayload } from '../../../src/retailIntegration/dtos/RetailUserEventPayload';
 import { ProductEventPayload } from '../../../src/retailIntegration/dtos/ProductEventPayload';
 import { InventoryEventPayload } from '../../../src/retailIntegration/dtos/InventoryEventPayload';
+import { RETAIL_EVENT_PIECES_MAX } from '../../../src/retailIntegration/constants/retailIntegrationLimits';
 
 function paths(errors: ValidationError[], prefix = ''): string[] {
     return errors.flatMap((e) => {
@@ -130,4 +131,11 @@ describe('InventoryEventPayload', () => {
         expect(await errorsOf(InventoryEventPayload, { ...movement, stock: [s, s] })).toContain('stock');
         expect(await errorsOf(InventoryEventPayload, { ...movement, stock: [{ ...s, qty: -1 }] })).toContain('stock.0.qty');
     });
+
+    it('acepta hasta RETAIL_EVENT_PIECES_MAX piezas y rechaza una más', async () => {
+        const piecesOf = (n: number) => Array.from({ length: n }, (_, i) => ({ ...piece, identifier: `35693803564${String(i).padStart(4, '0')}` }));
+        expect(RETAIL_EVENT_PIECES_MAX).toBe(30);
+        expect(await errorsOf(InventoryEventPayload, { ...movement, pieces: piecesOf(RETAIL_EVENT_PIECES_MAX) })).toEqual([]);
+        expect(await errorsOf(InventoryEventPayload, { ...movement, pieces: piecesOf(RETAIL_EVENT_PIECES_MAX + 1) })).toContain('pieces');
+    });
 });

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

@@ -20,8 +20,8 @@ function propsWithErrors<T extends object>(cls: ClassConstructor<T>, payload: ob
 }
 
 describe('enums de la revisión', () => {
-  it('ReconciliationEntityEnum trae las cuatro entidades', () => {
-    expect(Object.values(ReconciliationEntityEnum)).toEqual(['STORES', 'USERS', 'CATALOG', 'INVENTORY']);
+  it('ReconciliationEntityEnum trae las cinco entidades', () => {
+    expect(Object.values(ReconciliationEntityEnum)).toEqual(['STORES', 'USERS', 'CATALOG', 'INVENTORY', 'MOVEMENTS']);
   });
 
   it('ReconciliationRunStatusEnum trae los cuatro estados de la corrida', () => {
@@ -29,7 +29,7 @@ describe('enums de la revisión', () => {
   });
 
   it('ReconciliationTriggerEnum distingue el reloj del botón', () => {
-    expect(Object.values(ReconciliationTriggerEnum)).toEqual(['SCHEDULED', 'MANUAL', 'ACTIVATION']);
+    expect(Object.values(ReconciliationTriggerEnum)).toEqual(['SCHEDULED', 'MANUAL', 'ACTIVATION', 'DISCREPANCY', 'DAILY']);
   });
 
   it('InactiveReasonEnum distingue la baja de la revisión de la del evento', () => {

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

@@ -0,0 +1,109 @@
+import 'reflect-metadata';
+import { plainToInstance, type ClassConstructor } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import {
+    GetRetailInventoryRequest,
+    type GetRetailInventoryResponse,
+    ListRetailInventoryMovementsRequest,
+    type ListRetailInventoryMovementsResponse,
+    ReconciliationEntityEnum,
+    ReconciliationPageMessage,
+    ReconciliationTriggerEnum,
+} from '../../../src/retailIntegration';
+
+function propsWithErrors<T extends object>(cls: ClassConstructor<T>, payload: object): string[] {
+    return validateSync(plainToInstance(cls, payload)).map((e) => e.property);
+}
+
+const tenant = { tenantId: 'surekeep', retailerId: 'ret-1' };
+
+describe('ListRetailInventoryMovementsRequest', () => {
+    const valid = { ...tenant, from: '2026-08-17T19:55:00Z', to: '2026-08-17T21:00:00Z' };
+
+    it('acepta el rango con y sin paginación', () => {
+        expect(propsWithErrors(ListRetailInventoryMovementsRequest, valid)).toEqual([]);
+        expect(propsWithErrors(ListRetailInventoryMovementsRequest, { ...valid, limit: '200', nextToken: 'abc', runId: 'run-1' })).toEqual([]);
+    });
+
+    it('acepta un rango de 7 días exactos', () => {
+        expect(propsWithErrors(ListRetailInventoryMovementsRequest, { ...tenant, from: '2026-08-10T00:00:00Z', to: '2026-08-17T00:00:00Z' })).toEqual([]);
+    });
+
+    it.each([
+        ['to igual a from', '2026-08-17T20:00:00Z', '2026-08-17T20:00:00Z'],
+        ['to antes de from', '2026-08-17T20:00:00Z', '2026-08-17T19:00:00Z'],
+        ['más de 7 días', '2026-08-10T00:00:00Z', '2026-08-17T00:00:01Z'],
+    ])('rechaza %s', (_label, from, to) => {
+        expect(propsWithErrors(ListRetailInventoryMovementsRequest, { ...tenant, from, to })).toEqual(['to']);
+    });
+
+    it.each(['from', 'to'])('rechaza sin %s o con fecha sin zona', (field) => {
+        const payload: Record<string, unknown> = { ...valid };
+        delete payload[field];
+        expect(propsWithErrors(ListRetailInventoryMovementsRequest, payload)).toContain(field);
+        expect(propsWithErrors(ListRetailInventoryMovementsRequest, { ...valid, [field]: '2026-08-17T20:00:00' })).toContain(field);
+    });
+
+    it.each(['0', '201'])('rechaza limit=%p', (limit) => {
+        expect(propsWithErrors(ListRetailInventoryMovementsRequest, { ...valid, limit })).toEqual(['limit']);
+    });
+
+    it('la respuesta trae items y meta de página', () => {
+        const response: ListRetailInventoryMovementsResponse = {
+            items: [
+                {
+                    eventId: 'evt-1',
+                    eventType: 'InventoryMovementV1',
+                    occurredAt: '2026-08-17T20:32:07Z',
+                    payload: { movementType: 'SALE', storeId: '12', targetStoreId: null, pieces: [], stock: [] },
+                },
+            ],
+            meta: { count: 1, nextToken: null },
+        };
+        expect(response.meta.nextToken).toBeNull();
+    });
+});
+
+describe('GetRetailInventoryRequest paginado', () => {
+    it('acepta limit y nextToken opcionales', () => {
+        expect(propsWithErrors(GetRetailInventoryRequest, { ...tenant, storeId: '12', limit: '50', nextToken: 'abc' })).toEqual([]);
+        expect(propsWithErrors(GetRetailInventoryRequest, { ...tenant, storeId: '12', limit: '0' })).toEqual(['limit']);
+    });
+
+    it('la respuesta admite meta.count y meta.nextToken', () => {
+        const response: GetRetailInventoryResponse = {
+            pieces: [],
+            stock: [],
+            meta: { storeId: '12', generatedAt: '2026-08-17T15:00:00Z', count: 0, nextToken: null },
+        };
+        expect(response.meta.count).toBe(0);
+    });
+});
+
+describe('enums de revisión para movimientos', () => {
+    it('ReconciliationEntityEnum suma MOVEMENTS', () => {
+        expect(ReconciliationEntityEnum.MOVEMENTS).toBe('MOVEMENTS');
+    });
+
+    it('ReconciliationTriggerEnum suma DISCREPANCY y DAILY', () => {
+        expect(ReconciliationTriggerEnum.DISCREPANCY).toBe('DISCREPANCY');
+        expect(ReconciliationTriggerEnum.DAILY).toBe('DAILY');
+    });
+});
+
+describe('ReconciliationPageMessage con cursor y rango', () => {
+    const base = { ...tenant, runId: 'run-1', pageIndex: 0 };
+
+    it('acepta nextToken en inventario y from/to en movimientos', () => {
+        expect(propsWithErrors(ReconciliationPageMessage, { ...base, entity: 'INVENTORY', storeId: '12', nextToken: 'abc' })).toEqual([]);
+        expect(
+            propsWithErrors(ReconciliationPageMessage, { ...base, entity: 'MOVEMENTS', from: '2026-08-17T19:55:00Z', to: '2026-08-17T21:00:00Z' }),
+        ).toEqual([]);
+    });
+
+    it('rechaza nextToken vacío y fechas sin zona', () => {
+        expect(propsWithErrors(ReconciliationPageMessage, { ...base, entity: 'INVENTORY', nextToken: '' })).toEqual(['nextToken']);
+        expect(propsWithErrors(ReconciliationPageMessage, { ...base, entity: 'MOVEMENTS', from: '2026-08-17' })).toEqual(['from']);
+        expect(propsWithErrors(ReconciliationPageMessage, { ...base, entity: 'MOVEMENTS', to: 'ayer' })).toEqual(['to']);
+    });
+});

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

@@ -0,0 +1,120 @@
+import 'reflect-metadata';
+import { plainToInstance, type ClassConstructor } from 'class-transformer';
+import { validateSync, type ValidationError } from 'class-validator';
+import {
+    RetailSystemErrorBody,
+    RetailSystemInventoryResponse,
+    RetailSystemMovementsResponse,
+    RetailSystemPageMeta,
+    RetailSystemPageResponse,
+    RetailSystemSaleResponse,
+} from '../../../src/retailIntegration';
+
+function errorPaths(errors: ValidationError[], prefix = ''): string[] {
+    return errors.flatMap((error) => {
+        const path = prefix ? `${prefix}.${error.property}` : error.property;
+        return error.children?.length ? errorPaths(error.children, path) : [path];
+    });
+}
+
+function pathsWithErrors<T extends object>(cls: ClassConstructor<T>, payload: object): string[] {
+    return errorPaths(validateSync(plainToInstance(cls, payload)));
+}
+
+const movement = {
+    eventId: 'evt_01J8ZE5M8Y2Q4R7T1V3W6X8Z1C',
+    eventType: 'InventoryMovementV1',
+    occurredAt: '2026-08-17T20:32:07Z',
+    payload: { movementType: 'SALE', storeId: '12', targetStoreId: null, pieces: [], stock: [] },
+};
+
+describe('RetailSystemPageMeta', () => {
+    it('acepta la última página y una intermedia', () => {
+        expect(pathsWithErrors(RetailSystemPageMeta, { count: 0, nextToken: null })).toEqual([]);
+        expect(pathsWithErrors(RetailSystemPageMeta, { count: 200, nextToken: 'eyJpZCI6MTQwMH0' })).toEqual([]);
+    });
+
+    it.each([-1, 1.5, '3', undefined])('rechaza count=%p', (count) => {
+        expect(pathsWithErrors(RetailSystemPageMeta, { count, nextToken: null })).toEqual(['count']);
+    });
+
+    it.each([undefined, 7, 'x'.repeat(2049)])('rechaza nextToken=%p', (nextToken) => {
+        expect(pathsWithErrors(RetailSystemPageMeta, { count: 1, nextToken })).toEqual(['nextToken']);
+    });
+});
+
+describe('RetailSystemPageResponse', () => {
+    it('acepta data con renglones crudos', () => {
+        expect(pathsWithErrors(RetailSystemPageResponse, { data: [{ any: 'row' }], meta: { count: 1, nextToken: null } })).toEqual([]);
+    });
+
+    it('rechaza data que no es arreglo y meta inválida', () => {
+        expect(pathsWithErrors(RetailSystemPageResponse, { data: {}, meta: { count: 1, nextToken: null } })).toEqual(['data']);
+        expect(pathsWithErrors(RetailSystemPageResponse, { data: [], meta: { count: -1, nextToken: null } })).toEqual(['meta.count']);
+        expect(pathsWithErrors(RetailSystemPageResponse, { data: [] })).toEqual(['meta']);
+    });
+});
+
+describe('RetailSystemInventoryResponse', () => {
+    const valid = {
+        data: { pieces: [{ sku: 'SAM-A17' }], stock: [] },
+        meta: { storeId: '12', generatedAt: '2026-08-17T15:00:00Z', count: 1, nextToken: null },
+    };
+
+    it('acepta una página del inventario', () => {
+        expect(pathsWithErrors(RetailSystemInventoryResponse, valid)).toEqual([]);
+    });
+
+    it('rechaza pieces o stock que no son arreglo', () => {
+        expect(pathsWithErrors(RetailSystemInventoryResponse, { ...valid, data: { pieces: null, stock: [] } })).toEqual(['data.pieces']);
+        expect(pathsWithErrors(RetailSystemInventoryResponse, { ...valid, data: { pieces: [] } })).toEqual(['data.stock']);
+    });
+
+    it.each([
+        ['storeId', 'tienda/12'],
+        ['generatedAt', '2026-08-17 15:00'],
+        ['count', -2],
+        ['nextToken', ''.padEnd(2049, 'a')],
+    ])('rechaza meta.%s inválido', (field, value) => {
+        expect(pathsWithErrors(RetailSystemInventoryResponse, { ...valid, meta: { ...valid.meta, [field]: value } })).toEqual([`meta.${field}`]);
+    });
+});
+
+describe('RetailSystemSaleResponse', () => {
+    it.each(['58812', 'SALE-12_a.b:c', 'a/b#ñ'])('acepta externalSaleId=%p', (externalSaleId) => {
+        expect(pathsWithErrors(RetailSystemSaleResponse, { externalSaleId })).toEqual([]);
+    });
+
+    it.each(['', 'con espacio', ' 58812', 'x'.repeat(65), 58812, undefined])('rechaza externalSaleId=%p', (externalSaleId) => {
+        expect(pathsWithErrors(RetailSystemSaleResponse, { externalSaleId })).toEqual(['externalSaleId']);
+    });
+});
+
+describe('RetailSystemErrorBody', () => {
+    it('acepta el error con y sin lineIndex', () => {
+        expect(pathsWithErrors(RetailSystemErrorBody, { code: 'IDENTIFIER_NOT_AVAILABLE', msg: 'texto', lineIndex: 1 })).toEqual([]);
+        expect(pathsWithErrors(RetailSystemErrorBody, { code: 'VALIDATION_ERROR' })).toEqual([]);
+    });
+
+    it('rechaza code ausente o largo y lineIndex fuera de rango', () => {
+        expect(pathsWithErrors(RetailSystemErrorBody, {})).toEqual(['code']);
+        expect(pathsWithErrors(RetailSystemErrorBody, { code: 'X'.repeat(65) })).toEqual(['code']);
+        expect(pathsWithErrors(RetailSystemErrorBody, { code: 'X', lineIndex: 1000 })).toEqual(['lineIndex']);
+        expect(pathsWithErrors(RetailSystemErrorBody, { code: 'X', lineIndex: -1 })).toEqual(['lineIndex']);
+    });
+});
+
+describe('RetailSystemMovementsResponse', () => {
+    it('acepta movimientos con el sobre del webhook', () => {
+        expect(pathsWithErrors(RetailSystemMovementsResponse, { data: [movement], meta: { count: 1, nextToken: null } })).toEqual([]);
+        expect(pathsWithErrors(RetailSystemMovementsResponse, { data: [], meta: { count: 0, nextToken: null } })).toEqual([]);
+    });
+
+    it('rechaza un movimiento con sobre inválido', () => {
+        const bad = { ...movement, eventType: 'StoreUpsertedV1', occurredAt: '2026-08-17' };
+        expect(pathsWithErrors(RetailSystemMovementsResponse, { data: [bad], meta: { count: 1, nextToken: null } }).sort()).toEqual([
+            'data.0.eventType',
+            'data.0.occurredAt',
+        ]);
+    });
+});

package/bin/platformRbac/dtos/CreateTenantUserRequest.d.ts

@@ -6,7 +6,8 @@ import { PermissionScope } from '../enums/PermissionScope';
  * Consumido por el alta de usuario orquestada de SureKeep F1 (retail-org → RBAC → RetailUser) vía api-invoker.
  * - Usuario provisionado en estado INVITED (mitiga orphan si el paso siguiente en retail-org falla).
  * - Idempotente por identidad Cognito.
- * - `roleId`/`scope`/`scopeRef`: todos o ninguno; sin rol no hay invitación.
+ * - `roleId`/`scope`/`scopeRef`: todos o ninguno; sin rol exige `suppressInvitation: true`
+ *   y la invitación queda pendiente (`invitationPending`) hasta asignar el primer rol.
  * - `createdBy` = cognitoSub del admin real (audit + grantedBy del assignment).
  * - `customFields` = valores de los campos personalizados del tenant; si el correo ya tiene usuario, se fusionan.
  */

package/bin/platformRbac/dtos/CreateTenantUserRequest.js

@@ -23,7 +23,8 @@ const hasAnyGrantField = (o) => o.roleId !== undefined || o.scope !== undefined
  * Consumido por el alta de usuario orquestada de SureKeep F1 (retail-org → RBAC → RetailUser) vía api-invoker.
  * - Usuario provisionado en estado INVITED (mitiga orphan si el paso siguiente en retail-org falla).
  * - Idempotente por identidad Cognito.
- * - `roleId`/`scope`/`scopeRef`: todos o ninguno; sin rol no hay invitación.
+ * - `roleId`/`scope`/`scopeRef`: todos o ninguno; sin rol exige `suppressInvitation: true`
+ *   y la invitación queda pendiente (`invitationPending`) hasta asignar el primer rol.
  * - `createdBy` = cognitoSub del admin real (audit + grantedBy del assignment).
  * - `customFields` = valores de los campos personalizados del tenant; si el correo ya tiene usuario, se fusionan.
  */

package/bin/platformRbac/dtos/UpdateTenantUserEmailRequest.d.ts

@@ -0,0 +1,5 @@
+/** Body M2M que cambia el correo de un usuario del tenant; el correo se guarda en minúsculas. */
+export declare class UpdateTenantUserEmailRequest {
+    email: string;
+    actedBy: string;
+}

package/bin/platformRbac/dtos/UpdateTenantUserEmailRequest.js

@@ -0,0 +1,30 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UpdateTenantUserEmailRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/** Body M2M que cambia el correo de un usuario del tenant; el correo se guarda en minúsculas. */
+class UpdateTenantUserEmailRequest {
+}
+exports.UpdateTenantUserEmailRequest = UpdateTenantUserEmailRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_transformer_1.Transform)(({ value }) => (typeof value === 'string' ? value.trim().toLowerCase() : value)),
+    (0, class_validator_1.IsEmail)(),
+    __metadata("design:type", String)
+], UpdateTenantUserEmailRequest.prototype, "email", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], UpdateTenantUserEmailRequest.prototype, "actedBy", void 0);

package/bin/platformRbac/enums/Permission.d.ts

@@ -120,7 +120,8 @@ export declare enum Permission {
     PLATFORM_INTEGRATION_KEY_ISSUE = "platform.integration.key.issue",
     PLATFORM_INTEGRATION_KEY_REVOKE = "platform.integration.key.revoke",
     TENANT_INTEGRATION_DIAGNOSTIC = "tenant.integration.diagnostic",
-    TENANT_API_USER_MANAGE = "tenant.api_user.manage"
+    TENANT_API_USER_MANAGE = "tenant.api_user.manage",
+    PLATFORM_RETAIL_INTEGRATION_ACTIVATE = "platform.retail_integration.activate"
 }
 /**
  * Orden CANÓNICO y APPEND-ONLY de los permisos para el bitset del token.

package/bin/platformRbac/enums/Permission.js

@@ -166,6 +166,8 @@ var Permission;
     Permission["TENANT_INTEGRATION_DIAGNOSTIC"] = "tenant.integration.diagnostic";
     // Alta, rotación de secreto y edición de IPs de usuarios de API; se exige además de tenant.user.create.
     Permission["TENANT_API_USER_MANAGE"] = "tenant.api_user.manage";
+    // Activa la integración de un retailer externo (Zentral); scope PLATFORM.
+    Permission["PLATFORM_RETAIL_INTEGRATION_ACTIVATE"] = "platform.retail_integration.activate";
 })(Permission || (exports.Permission = Permission = {}));
 /**
  * Orden CANÓNICO y APPEND-ONLY de los permisos para el bitset del token.
@@ -286,6 +288,7 @@ exports.PERMISSION_BIT_ORDER = [
     Permission.PLATFORM_INTEGRATION_KEY_REVOKE,
     Permission.TENANT_INTEGRATION_DIAGNOSTIC,
     Permission.TENANT_API_USER_MANAGE,
+    Permission.PLATFORM_RETAIL_INTEGRATION_ACTIVATE,
 ];
 function djb2(input) {
     let h = 5381;

package/bin/platformRbac/index.d.ts

@@ -73,6 +73,7 @@ export type { ListTenantUsersResponse } from './dtos/ListTenantUsersResponse';
 export type { TenantUserListItemResponse } from './dtos/TenantUserListItemResponse';
 export type { GetTenantUserResponse } from './dtos/GetTenantUserResponse';
 export * from './dtos/UpdateTenantUserRequest';
+export * from './dtos/UpdateTenantUserEmailRequest';
 export * from './dtos/DeleteTenantUserRequest';
 export * from './dtos/DisableTenantUserRequest';
 export * from './dtos/EnableTenantUserRequest';

package/bin/platformRbac/index.js

@@ -120,6 +120,7 @@ __exportStar(require("./dtos/UpdateIntegrationRequest"), exports);
 __exportStar(require("./dtos/UpdateLevelEntityRequest"), exports);
 __exportStar(require("./dtos/DeleteLevelEntityRequest"), exports);
 __exportStar(require("./dtos/UpdateTenantUserRequest"), exports);
+__exportStar(require("./dtos/UpdateTenantUserEmailRequest"), exports);
 __exportStar(require("./dtos/DeleteTenantUserRequest"), exports);
 __exportStar(require("./dtos/DisableTenantUserRequest"), exports);
 __exportStar(require("./dtos/EnableTenantUserRequest"), exports);

package/bin/retailIntegration/constants/retailIntegrationLimits.d.ts

@@ -20,3 +20,28 @@ export declare const RETAIL_SKU_PATTERN: RegExp;
 export declare const RETAIL_DECIMAL_PATTERN: RegExp;
 /** Tope de identificadores por consulta de inventario en vivo. */
 export declare const RETAIL_LIVE_CHECK_IDENTIFIERS_MAX = 50;
+/** Tope de piezas por evento `InventoryMovementV1`; más se rechaza con INVALID_PAYLOAD. */
+export declare const RETAIL_EVENT_PIECES_MAX = 30;
+/** Tope de ids y códigos libres del retailer, como `externalId`. */
+export declare const RETAIL_ID_TEXT_MAX_LENGTH = 64;
+/** Tope de textos cortos de los payloads: nombres, dirección, teléfono, marca, modelo, `identifier`. */
+export declare const RETAIL_SHORT_TEXT_MAX_LENGTH = 255;
+/** Tope de textos largos de los payloads: descripción y referencia. */
+export declare const RETAIL_LONG_TEXT_MAX_LENGTH = 1000;
+/** Tope de existencias por evento `InventoryMovementV1`. */
+export declare const RETAIL_EVENT_STOCK_MAX = 200;
+/** Tope de financieras elegibles por producto. */
+export declare const RETAIL_ELIGIBLE_FINANCIERS_MAX = 50;
+/** Decimal de los eventos del retailer: hasta 12 enteros y dos decimales, nunca negativo. */
+export declare const RETAIL_EVENT_DECIMAL_PATTERN: RegExp;
+/** Tope del `nextToken` opaco que devuelve Zentral. */
+export declare const RETAIL_NEXT_TOKEN_MAX_LENGTH = 2048;
+/** Id que asigna Zentral, como `externalSaleId`: no vacío, sin espacios y de a lo más 64. */
+export declare const RETAIL_EXTERNAL_ID_PATTERN: RegExp;
+/** Tope del `code` en el cuerpo de error de Zentral. */
+export declare const RETAIL_ERROR_CODE_MAX_LENGTH = 64;
+/** Rango de `lineIndex` en un error de línea de venta. */
+export declare const RETAIL_LINE_INDEX_MIN = 0;
+export declare const RETAIL_LINE_INDEX_MAX = 999;
+/** Rango máximo de `GET /inventory/movements`: 7 días en milisegundos. */
+export declare const RETAIL_MOVEMENTS_RANGE_MAX_MS: number;