@fiado/type-kit 3.472.0 → 3.473.0

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

@@ -0,0 +1,123 @@
+import 'reflect-metadata';
+import { plainToInstance, type ClassConstructor } from 'class-transformer';
+import { validateSync, type ValidationError } from 'class-validator';
+import {
+  BackofficeCreateProductRequest,
+  BackofficeRegisterAdjustmentRequest,
+  BackofficeUpdateProductRequest,
+  InventoryMovementReasonEnum,
+  InventoryMovementTypeEnum,
+  Product,
+  ProductCategoryEnum,
+  TrackingModeEnum,
+  type InventoryMovementEntry,
+  type ProductResponse,
+} from '../../../src/retailCatalog';
+
+function errorsOf<T extends object>(cls: ClassConstructor<T>, payload: object): string[] {
+  return validateSync(plainToInstance(cls, payload) as object, { whitelist: true, forbidNonWhitelisted: true }).map(
+    (e: ValidationError) => e.property,
+  );
+}
+
+const sheet = {
+  salePriority: 100,
+  highlights: ['Cámara de 50 MP', 'Batería de 5000 mAh'],
+  warrantyMonths: 12,
+  launchDate: '2026-03-01',
+  specs: { ram: '8GB', pantalla: '6.5"' },
+};
+
+const createOk = {
+  sku: 'PH-A15',
+  category: ProductCategoryEnum.PHONE,
+  trackingMode: TrackingModeEnum.IMEI,
+  sellable: true,
+  showInSalesFlow: true,
+};
+
+const productWrites: [string, ClassConstructor<object>, object][] = [
+  ['BackofficeCreateProductRequest', BackofficeCreateProductRequest, createOk],
+  ['BackofficeUpdateProductRequest', BackofficeUpdateProductRequest, {}],
+];
+
+describe.each(productWrites)('%s — prioridad de venta y ficha comercial', (_name, cls, base) => {
+  it('acepta la prioridad y la ficha completa', () => {
+    expect(errorsOf(cls, { ...base, ...sheet })).toEqual([]);
+  });
+  it('sigue aceptando el cuerpo sin los campos nuevos', () => {
+    expect(errorsOf(cls, base)).toEqual([]);
+  });
+  it.each([0, 100])('acepta salePriority %p (límite)', (salePriority) => {
+    expect(errorsOf(cls, { ...base, salePriority })).toEqual([]);
+  });
+  it.each([-1, 101, 50.5, '50'])('rechaza salePriority %p', (salePriority) => {
+    expect(errorsOf(cls, { ...base, salePriority })).toContain('salePriority');
+  });
+  it('rechaza highlights que no son lista de textos o traen uno en blanco', () => {
+    expect(errorsOf(cls, { ...base, highlights: 'Cámara' })).toContain('highlights');
+    expect(errorsOf(cls, { ...base, highlights: ['ok', ' '] })).toContain('highlights');
+    expect(errorsOf(cls, { ...base, highlights: [1] })).toContain('highlights');
+  });
+  it.each([-1, 1.5, '12'])('rechaza warrantyMonths %p', (warrantyMonths) => {
+    expect(errorsOf(cls, { ...base, warrantyMonths })).toContain('warrantyMonths');
+  });
+  it('acepta warrantyMonths 0 (sin garantía)', () => {
+    expect(errorsOf(cls, { ...base, warrantyMonths: 0 })).toEqual([]);
+  });
+  it.each(['marzo 2026', '2026-13-01', 20260301])('rechaza launchDate %p', (launchDate) => {
+    expect(errorsOf(cls, { ...base, launchDate })).toContain('launchDate');
+  });
+  it('rechaza specs que no son objeto', () => {
+    expect(errorsOf(cls, { ...base, specs: 'ram 8GB' })).toContain('specs');
+    expect(errorsOf(cls, { ...base, specs: [['ram', '8GB']] })).toContain('specs');
+  });
+});
+
+describe('Product — prioridad de venta y ficha comercial en la lectura', () => {
+  it('acepta los campos nuevos y sigue válido sin ellos', () => {
+    const product = new Product();
+    product.salePriority = 100;
+    product.highlights = ['Cámara de 50 MP'];
+    product.warrantyMonths = 12;
+    product.launchDate = '2026-03-01';
+    const response: ProductResponse = product;
+    expect(response.salePriority).toBe(100);
+    expect(response.highlights).toEqual(['Cámara de 50 MP']);
+    expect(response.warrantyMonths).toBe(12);
+    expect(response.launchDate).toBe('2026-03-01');
+    const bare = new Product();
+    expect(bare.salePriority).toBeUndefined();
+    expect(bare.highlights).toBeUndefined();
+  });
+});
+
+describe('BackofficeRegisterAdjustmentRequest — reversesMovementId', () => {
+  const ok = { storeId: 'ST-1', sku: 'PH-A15', qty: 1, reason: InventoryMovementReasonEnum.ADJUSTMENT };
+  it('acepta el ajuste que corrige un movimiento', () => {
+    expect(errorsOf(BackofficeRegisterAdjustmentRequest, { ...ok, reversesMovementId: 'mov-123' })).toEqual([]);
+  });
+  it('sigue aceptando el ajuste sin él', () => {
+    expect(errorsOf(BackofficeRegisterAdjustmentRequest, ok)).toEqual([]);
+  });
+  it.each(['', ' ', 'mov 1', 42])('rechaza reversesMovementId %p', (reversesMovementId) => {
+    expect(errorsOf(BackofficeRegisterAdjustmentRequest, { ...ok, reversesMovementId })).toContain('reversesMovementId');
+  });
+});
+
+describe('InventoryMovementEntry — reason', () => {
+  it('expone el motivo del movimiento y sigue válido sin él', () => {
+    const base: InventoryMovementEntry = {
+      storeId: 'ST-1',
+      sku: 'PH-A15',
+      type: InventoryMovementTypeEnum.ADJUSTMENT,
+      qty: 1,
+      identifier: null,
+      occurredAt: '2026-09-28T10:00:00.000Z',
+      createdBy: 'user-1',
+    };
+    const withReason: InventoryMovementEntry = { ...base, reason: InventoryMovementReasonEnum.SHRINKAGE };
+    expect(withReason.reason).toBe('SHRINKAGE');
+    expect(base.reason).toBeUndefined();
+  });
+});

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 al estado de pieza sin quitar los existentes', () => {
+  it('agrega IN_TRANSIT y HELD al estado de pieza sin quitar los existentes', () => {
     expect(Object.values(RetailCatalog.InventoryItemStatusEnum)).toEqual([
-      'AVAILABLE', 'RESERVED', 'SOLD', 'RETURNED', 'DAMAGED', 'IN_TRANSIT',
+      'AVAILABLE', 'RESERVED', 'SOLD', 'RETURNED', 'DAMAGED', 'IN_TRANSIT', 'HELD',
     ]);
   });
 

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

@@ -0,0 +1,152 @@
+import 'reflect-metadata';
+import { plainToInstance, type ClassConstructor } from 'class-transformer';
+import { validateSync, type ValidationError } from 'class-validator';
+import {
+  HoldStockRequest,
+  type HoldStockResponse,
+  InventoryInboundMessageTypeEnum,
+  InventoryItemStatusEnum,
+  InventoryReturnMessage,
+  InventorySaleAppliedMessage,
+  ProductCategoryEnum,
+  ReservePurposeEnum,
+  ReserveStockRequest,
+  type StoreCatalogItem,
+  SuggestPiecesQuery,
+} from '../../../src/retailCatalog';
+
+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];
+  });
+}
+
+function errorsOf<T extends object>(cls: ClassConstructor<T>, payload: object): string[] {
+  return paths(validateSync(plainToInstance(cls, payload) as object));
+}
+
+const saleLine = { lineId: 'L1', sku: 'KIT-1', qty: 1, components: [{ sku: 'SIM-1', qty: 1, identifiers: ['8952'] }] };
+
+describe('InventoryItemStatusEnum — HELD', () => {
+  it('agrega HELD sin quitar los existentes', () => {
+    expect(InventoryItemStatusEnum.HELD).toBe('HELD');
+    expect(InventoryItemStatusEnum.AVAILABLE).toBe('AVAILABLE');
+    expect(InventoryItemStatusEnum.IN_TRANSIT).toBe('IN_TRANSIT');
+  });
+});
+
+describe('HoldStockRequest', () => {
+  const ok = {
+    lineId: 'L1',
+    reservationId: 'r',
+    sessionId: 's',
+    retailerId: 'ret',
+    components: [{ sku: 'PHONE-1', identifiers: ['356938035643809'] }],
+  };
+  it('acepta una línea con sus componentes', () => expect(errorsOf(HoldStockRequest, ok)).toEqual([]));
+  it('exige lineId y reservationId de la línea', () => {
+    const { lineId: _l, reservationId: _r, ...rest } = ok;
+    expect(errorsOf(HoldStockRequest, rest)).toEqual(expect.arrayContaining(['lineId', 'reservationId']));
+  });
+  it('exige sessionId y retailerId', () => {
+    const { sessionId: _s, retailerId: _r, ...rest } = ok;
+    expect(errorsOf(HoldStockRequest, rest)).toEqual(expect.arrayContaining(['sessionId', 'retailerId']));
+  });
+  it('rechaza sin componentes', () => expect(errorsOf(HoldStockRequest, { ...ok, components: [] })).toContain('components'));
+  it('valida cada componente anidado', () => {
+    expect(errorsOf(HoldStockRequest, { ...ok, components: [{ sku: 'PHONE-1', identifiers: [3] }] })).toContain(
+      'components.0.identifiers',
+    );
+    expect(errorsOf(HoldStockRequest, { ...ok, components: [{ identifiers: ['x'] }] })).toContain('components.0.sku');
+  });
+  it('la respuesta es el espejo de la línea', () => {
+    const res: HoldStockResponse = { lineId: 'L1', reservationId: 'r', sessionId: 's', components: ok.components };
+    expect(res.components[0].identifiers).toEqual(['356938035643809']);
+  });
+});
+
+describe('InventorySaleAppliedMessage', () => {
+  const ok = {
+    type: 'SALE_APPLIED',
+    tenantId: 't',
+    storeId: 'st',
+    saleId: 'sale',
+    soldAt: '2026-09-28T10:00:00.000Z',
+    sessionId: 's',
+    retailerId: 'ret',
+    lines: [saleLine],
+  };
+  it('acepta el aviso de venta completo', () => expect(errorsOf(InventorySaleAppliedMessage, ok)).toEqual([]));
+  it('fija el type en SALE_APPLIED', () => {
+    expect(InventoryInboundMessageTypeEnum.SALE_APPLIED).toBe('SALE_APPLIED');
+    expect(errorsOf(InventorySaleAppliedMessage, { ...ok, type: 'RETURN' })).toContain('type');
+  });
+  it('exige tenantId, storeId, saleId y soldAt ISO', () => {
+    const { tenantId: _t, storeId: _s, saleId: _sa, ...rest } = ok;
+    expect(errorsOf(InventorySaleAppliedMessage, { ...rest, soldAt: 'ayer' })).toEqual(
+      expect.arrayContaining(['tenantId', 'storeId', 'saleId', 'soldAt']),
+    );
+  });
+  it('valida las líneas como SellStockRequest', () => {
+    expect(errorsOf(InventorySaleAppliedMessage, { ...ok, lines: [{ ...saleLine, qty: 0 }] })).toContain('lines.0.qty');
+  });
+});
+
+describe('InventoryReturnMessage', () => {
+  const ok = {
+    type: 'RETURN',
+    tenantId: 't',
+    storeId: 'st',
+    sessionId: 's',
+    returnedAt: '2026-09-29T10:00:00.000Z',
+    saleId: 'sale',
+    retailerId: 'ret',
+    soldAt: '2026-09-28T10:00:00.000Z',
+    lines: [saleLine],
+  };
+  it('acepta el aviso de devolución completo', () => expect(errorsOf(InventoryReturnMessage, ok)).toEqual([]));
+  it('fija el type en RETURN', () => {
+    expect(InventoryInboundMessageTypeEnum.RETURN).toBe('RETURN');
+    expect(errorsOf(InventoryReturnMessage, { ...ok, type: 'SALE_APPLIED' })).toContain('type');
+  });
+  it('exige tenantId, storeId, sessionId y returnedAt ISO', () => {
+    const { tenantId: _t, storeId: _s, sessionId: _se, ...rest } = ok;
+    expect(errorsOf(InventoryReturnMessage, { ...rest, returnedAt: 'hoy' })).toEqual(
+      expect.arrayContaining(['tenantId', 'storeId', 'sessionId', 'returnedAt']),
+    );
+  });
+  it('valida las líneas como ReturnStockRequest', () => {
+    expect(errorsOf(InventoryReturnMessage, { ...ok, lines: [] })).toContain('lines');
+  });
+});
+
+describe('ReserveStockRequest.purpose', () => {
+  const ok = { sessionId: 's', lineId: 'L1', reservationId: 'r', retailerId: 'ret', sku: 'SKU-1', qty: 1 };
+  it('sigue válido sin purpose', () => expect(errorsOf(ReserveStockRequest, ok)).toEqual([]));
+  it('acepta purpose GIFT', () => {
+    expect(ReservePurposeEnum.GIFT).toBe('GIFT');
+    expect(errorsOf(ReserveStockRequest, { ...ok, purpose: 'GIFT' })).toEqual([]);
+  });
+  it('rechaza un purpose desconocido', () => expect(errorsOf(ReserveStockRequest, { ...ok, purpose: 'PROMO' })).toContain('purpose'));
+});
+
+describe('SuggestPiecesQuery.sessionId', () => {
+  const ok = { sku: 'SKU-1', prefix: '3569' };
+  it('sigue válido sin sessionId', () => expect(errorsOf(SuggestPiecesQuery, ok)).toEqual([]));
+  it('acepta sessionId', () => expect(errorsOf(SuggestPiecesQuery, { ...ok, sessionId: 's' })).toEqual([]));
+  it('rechaza sessionId vacío', () => expect(errorsOf(SuggestPiecesQuery, { ...ok, sessionId: '' })).toContain('sessionId'));
+});
+
+describe('StoreCatalogItem.components[].category', () => {
+  it('acepta la categoría por componente y sigue válido sin ella', () => {
+    const item: Pick<StoreCatalogItem, 'components'> = {
+      components: [
+        { sku: 'PHONE-1', qty: 1, category: ProductCategoryEnum.PHONE },
+        { sku: 'SIM-1', qty: 1 },
+      ],
+    };
+    expect(item.components?.[0].category).toBe(ProductCategoryEnum.PHONE);
+    expect(item.components?.[1].category).toBeUndefined();
+  });
+});

package/_test_/unit/retailPromotions/computeBudgetUsedBps.test.ts

@@ -0,0 +1,30 @@
+import 'reflect-metadata';
+import { computeBudgetUsedBps } from '../../../src/retailPromotions/index';
+
+describe('computeBudgetUsedBps', () => {
+  it('devuelve null si ninguna promo tiene tope', () => {
+    expect(computeBudgetUsedBps([])).toBeNull();
+    expect(computeBudgetUsedBps([{ budgetMaxCents: null, budgetConsumedCents: 5000 }])).toBeNull();
+  });
+
+  it('agrega consumido sobre tope solo de las promos con tope', () => {
+    const bps = computeBudgetUsedBps([
+      { budgetMaxCents: 100000, budgetConsumedCents: 25000 },
+      { budgetMaxCents: 300000, budgetConsumedCents: 75000 },
+      { budgetMaxCents: null, budgetConsumedCents: 999999 },
+    ]);
+    expect(bps).toBe(2500);
+  });
+
+  it('redondea hacia abajo a punto base entero', () => {
+    expect(computeBudgetUsedBps([{ budgetMaxCents: 300, budgetConsumedCents: 100 }])).toBe(3333);
+  });
+
+  it('refleja un consumo por arriba del tope sin recortarlo', () => {
+    expect(computeBudgetUsedBps([{ budgetMaxCents: 1000, budgetConsumedCents: 1100 }])).toBe(11000);
+  });
+
+  it('con tope 0 lo trata como sin presupuesto disponible', () => {
+    expect(computeBudgetUsedBps([{ budgetMaxCents: 0, budgetConsumedCents: 0 }])).toBeNull();
+  });
+});

package/_test_/unit/retailPromotions/constants.test.ts

@@ -0,0 +1,71 @@
+import 'reflect-metadata';
+import {
+  BONUS_PRE_MONEY_CODES,
+  PRE_HANDLER_HTTP_STATUSES,
+  RETAIL_PROMOTIONS_ERROR_HTTP_STATUS,
+  RetailPromotionsErrorCodeEnum,
+  SalePromotionStatusEnum as S,
+  SalePromotionTransitionEnum as T,
+  SalePromotionLeverEnum,
+  resolveSalePromotionTransition,
+} from '../../../src/retailPromotions/index';
+
+describe('resolveSalePromotionTransition', () => {
+  it.each([
+    [S.DRAFT, T.PUBLISH, S.ACTIVE],
+    [S.ACTIVE, T.PAUSE, S.PAUSED],
+    [S.PAUSED, T.RESUME, S.ACTIVE],
+    [S.ACTIVE, T.EXPIRE, S.EXPIRED],
+    [S.PAUSED, T.EXPIRE, S.EXPIRED],
+    [S.DRAFT, T.ARCHIVE, S.ARCHIVED],
+    [S.EXPIRED, T.ARCHIVE, S.ARCHIVED],
+  ])('%s + %s → %s', (from, transition, to) => {
+    expect(resolveSalePromotionTransition(from, transition)).toBe(to);
+  });
+
+  it.each([
+    [S.DRAFT, T.PAUSE],
+    [S.DRAFT, T.EXPIRE],
+    [S.ACTIVE, T.PUBLISH],
+    [S.EXPIRED, T.RESUME],
+    [S.ARCHIVED, T.ARCHIVE],
+    [S.ARCHIVED, T.PUBLISH],
+  ])('%s + %s no se permite', (from, transition) => {
+    expect(resolveSalePromotionTransition(from, transition)).toBeNull();
+  });
+});
+
+describe('catálogo de errores', () => {
+  it('cada code tiene su status del catálogo cerrado', () => {
+    for (const code of Object.values(RetailPromotionsErrorCodeEnum)) {
+      expect([404, 409, 422]).toContain(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS[code]);
+    }
+    expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS.CODE_NOT_FOUND).toBe(404);
+    expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS.DISCOUNT_AFTER_QUOTE).toBe(409);
+    expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS.CODE_NOT_OWNED).toBe(422);
+    expect(Object.keys(RetailPromotionsErrorCodeEnum)).toHaveLength(16);
+  });
+
+  it('promo y código con rangos, signo o palancas inválidos son 422', () => {
+    expect(RetailPromotionsErrorCodeEnum.INVALID_SALE_PROMOTION).toBe('INVALID_SALE_PROMOTION');
+    expect(RetailPromotionsErrorCodeEnum.INVALID_DISCOUNT_CODE).toBe('INVALID_DISCOUNT_CODE');
+    expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS.INVALID_SALE_PROMOTION).toBe(422);
+    expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS.INVALID_DISCOUNT_CODE).toBe(422);
+  });
+});
+
+describe('palancas', () => {
+  it('son siete', () => {
+    expect(Object.values(SalePromotionLeverEnum)).toHaveLength(7);
+  });
+});
+
+describe('lista pre-dinero del bono', () => {
+  it('es la whitelist del wizard: SYSTEM_ERROR queda fuera', () => {
+    expect(BONUS_PRE_MONEY_CODES.has('ACCOUNT_NOT_FOUND')).toBe(true);
+    expect(BONUS_PRE_MONEY_CODES.has('IDEMPOTENCY_KEY_REQUIRED')).toBe(true);
+    expect(BONUS_PRE_MONEY_CODES.has('SYSTEM_ERROR')).toBe(false);
+    expect(BONUS_PRE_MONEY_CODES.size).toBe(9);
+    expect([...PRE_HANDLER_HTTP_STATUSES].sort()).toEqual([401, 403, 404, 405]);
+  });
+});

package/_test_/unit/retailPromotions/discountCodeAndWizardRequests.test.ts

@@ -0,0 +1,84 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+  ChangeDiscountCodeStatusRequest,
+  CreateDiscountCodeRequest,
+  EvaluateSalePromotionsRequest,
+  HoldSalePromotionRequest,
+  ListDiscountCodesQuery,
+  ListStoreSalePromotionsQuery,
+} from '../../../src/retailPromotions/index';
+
+type Dto = new () => object;
+
+const errorPaths = async (dtoClass: Dto, raw: Record<string, unknown>): Promise<string[]> => {
+  const errors = await validate(plainToInstance(dtoClass, raw) as object);
+  const walk = (list: typeof errors, prefix: string): string[] =>
+    list.flatMap((e) => {
+      const path = prefix ? `${prefix}.${e.property}` : e.property;
+      return e.children && e.children.length > 0 ? walk(e.children, path) : [path];
+    });
+  return walk(errors, '');
+};
+
+describe('CreateDiscountCodeRequest', () => {
+  const base = { codeText: 'BUENFIN', discount: { type: 'AMOUNT', amountCents: 20000 } };
+
+  it('valida el alta mínima', async () => {
+    expect(await errorPaths(CreateDiscountCodeRequest, base)).toHaveLength(0);
+  });
+
+  it('rechaza texto vacío o demasiado largo', async () => {
+    expect(await errorPaths(CreateDiscountCodeRequest, { ...base, codeText: '' })).toContain('codeText');
+    expect(await errorPaths(CreateDiscountCodeRequest, { codeText: 'X' })).toContain('discount');
+    expect(await errorPaths(CreateDiscountCodeRequest, { ...base, codeText: 'X'.repeat(33) })).toContain('codeText');
+  });
+
+  it('valida el descuento anidado, los usos enteros y el appliesTo', async () => {
+    const paths = await errorPaths(CreateDiscountCodeRequest, {
+      ...base,
+      discount: { type: 'PERCENTAGE' },
+      maxUses: 1.5,
+      appliesTo: 'OTRA',
+    });
+    expect(paths).toEqual(expect.arrayContaining(['discount.percentBps', 'maxUses', 'appliesTo']));
+  });
+});
+
+describe('ChangeDiscountCodeStatusRequest', () => {
+  it('solo acepta VOID', async () => {
+    expect(await errorPaths(ChangeDiscountCodeStatusRequest, { transition: 'VOID' })).toHaveLength(0);
+    expect(await errorPaths(ChangeDiscountCodeStatusRequest, { transition: 'ACTIVATE' })).toContain('transition');
+  });
+});
+
+describe('ListDiscountCodesQuery', () => {
+  it('acepta estados de código y de cupón, y rechaza otros', async () => {
+    expect(await errorPaths(ListDiscountCodesQuery, { origin: 'SALE_COUPON', status: 'USED' })).toHaveLength(0);
+    expect(await errorPaths(ListDiscountCodesQuery, { origin: 'ADMIN', status: 'EXHAUSTED' })).toHaveLength(0);
+    expect(await errorPaths(ListDiscountCodesQuery, { status: 'DRAFT' })).toContain('status');
+  });
+});
+
+describe('piezas del wizard', () => {
+  it('listar y evaluar exigen sessionId', async () => {
+    expect(await errorPaths(ListStoreSalePromotionsQuery, {})).toContain('sessionId');
+    expect(await errorPaths(EvaluateSalePromotionsRequest, { sessionId: '' })).toContain('sessionId');
+    expect(await errorPaths(EvaluateSalePromotionsRequest, { sessionId: 's1', discountCode: 'BUENFIN' })).toHaveLength(0);
+  });
+
+  it('apartar acepta null como «Ninguna» y valida versión entera y SKUs de regalo', async () => {
+    expect(await errorPaths(HoldSalePromotionRequest, { promotionId: null, discountCode: null })).toHaveLength(0);
+    expect(
+      await errorPaths(HoldSalePromotionRequest, { promotionId: 'p1', promotionVersion: 2, giftSkus: ['SKU-9'] }),
+    ).toHaveLength(0);
+    expect(
+      await errorPaths(HoldSalePromotionRequest, { promotionId: 'p1', promotionVersion: '2', giftSkus: [1] }),
+    ).toEqual(expect.arrayContaining(['promotionVersion', 'giftSkus']));
+  });
+
+  it('apartar pide versión cuando trae promo', async () => {
+    expect(await errorPaths(HoldSalePromotionRequest, { promotionId: 'p1' })).toContain('promotionVersion');
+  });
+});

package/_test_/unit/retailPromotions/salePromotionRequests.test.ts

@@ -0,0 +1,151 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+  ChangeSalePromotionStatusRequest,
+  CreateSalePromotionRequest,
+  DiscountTypeEnum,
+  ListSalePromotionLogQuery,
+  ListSalePromotionsQuery,
+  PromotionAppliesToEnum,
+  SalePromotionTransitionEnum,
+  UpdateSalePromotionRequest,
+} from '../../../src/retailPromotions/index';
+
+type Dto = new () => object;
+
+/** Rutas de propiedad con error, incluidas las anidadas (`levers.gift.skus`). */
+const errorPaths = async (dtoClass: Dto, raw: Record<string, unknown>): Promise<string[]> => {
+  const instance = plainToInstance(dtoClass, raw);
+  const errors = await validate(instance as object);
+  const walk = (list: typeof errors, prefix: string): string[] =>
+    list.flatMap((e) => {
+      const path = prefix ? `${prefix}.${e.property}` : e.property;
+      return e.children && e.children.length > 0 ? walk(e.children, path) : [path];
+    });
+  return walk(errors, '');
+};
+
+const base = {
+  name: 'Regalo de audífonos',
+  customerText: 'Llévate unos audífonos gratis',
+  levers: { deviceDiscount: { type: 'AMOUNT', amountCents: 50000 } },
+};
+
+describe('CreateSalePromotionRequest', () => {
+  it('valida el alta mínima y deja appliesTo ausente para que el lambda ponga el default', async () => {
+    const dto = plainToInstance(CreateSalePromotionRequest, base);
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.appliesTo).toBeUndefined();
+    expect(dto.levers.deviceDiscount?.type).toBe(DiscountTypeEnum.AMOUNT);
+  });
+
+  it('exige nombre no vacío y palancas', async () => {
+    const paths = await errorPaths(CreateSalePromotionRequest, { customerText: 'x', name: '' });
+    expect(paths).toEqual(expect.arrayContaining(['name', 'levers']));
+  });
+
+  it('rechaza porcentaje en puntos base con decimales', async () => {
+    const paths = await errorPaths(CreateSalePromotionRequest, {
+      ...base,
+      levers: { deviceDiscount: { type: 'PERCENTAGE', percentBps: 12.5 } },
+    });
+    expect(paths).toContain('levers.deviceDiscount.percentBps');
+  });
+
+  it('pide el campo que corresponde al tipo de descuento', async () => {
+    const amount = await errorPaths(CreateSalePromotionRequest, {
+      ...base,
+      levers: { deviceDiscount: { type: 'AMOUNT', percentBps: 1000 } },
+    });
+    expect(amount).toContain('levers.deviceDiscount.amountCents');
+    const percent = await errorPaths(CreateSalePromotionRequest, {
+      ...base,
+      levers: { deviceDiscount: { type: 'PERCENTAGE', percentBps: 1000 } },
+    });
+    expect(percent).toHaveLength(0);
+  });
+
+  it('regalo por lista exige SKUs; por gama exige categoría y precio máximo', async () => {
+    const list = await errorPaths(CreateSalePromotionRequest, {
+      ...base,
+      levers: { gift: { mode: 'LIST', chooseCount: 1 } },
+    });
+    expect(list).toContain('levers.gift.skus');
+    const range = await errorPaths(CreateSalePromotionRequest, {
+      ...base,
+      levers: { gift: { mode: 'RANGE', chooseCount: 1 } },
+    });
+    expect(range).toEqual(expect.arrayContaining(['levers.gift.category', 'levers.gift.maxPriceCents']));
+    const ok = await errorPaths(CreateSalePromotionRequest, {
+      ...base,
+      levers: { gift: { mode: 'RANGE', category: 'AUDIO', maxPriceCents: 30000, chooseCount: 1 } },
+    });
+    expect(ok).toHaveLength(0);
+  });
+
+  it('valida las 7 palancas juntas', async () => {
+    const paths = await errorPaths(CreateSalePromotionRequest, {
+      ...base,
+      levers: {
+        deviceDiscount: { type: 'PERCENTAGE', percentBps: 1000 },
+        accessoryDiscount: { percentBps: 2000, maxAmountCents: null },
+        gift: { mode: 'LIST', skus: ['SKU-1'], chooseCount: 1 },
+        coupon: { type: 'AMOUNT', amountCents: 20000, validityDays: 30, scope: 'CHAIN' },
+        airtime: { rechargeCount: 3, rechargeAmountCents: 10000 },
+        extendedWarranty: { extraMonths: 6, costCents: 45000 },
+        walletBonus: { amountCents: 15000 },
+      },
+      appliesTo: 'ANY_FINANCIER',
+      scope: { tiers: ['HIGH'], productCategories: ['PHONE'], skus: null, storeIds: ['S1'] },
+      segmentation: { segmentIds: ['SEG_GOLD'], requiresActiveSurekeepCredit: true },
+      budgetMaxCents: null,
+      validFrom: '2026-10-01',
+      validUntil: null,
+      oncePerCustomer: true,
+    });
+    expect(paths).toHaveLength(0);
+  });
+
+  it('rechaza cupón sin alcance válido, appliesTo desconocido y fecha no ISO', async () => {
+    const paths = await errorPaths(CreateSalePromotionRequest, {
+      ...base,
+      levers: { coupon: { type: 'AMOUNT', amountCents: 100, validityDays: 30, scope: 'WORLD' } },
+      appliesTo: 'ANY',
+      validUntil: 'el viernes',
+      scope: { tiers: ['GIGANTE'] },
+    });
+    expect(paths).toEqual(
+      expect.arrayContaining(['levers.coupon.scope', 'appliesTo', 'validUntil', 'scope.tiers']),
+    );
+  });
+});
+
+describe('UpdateSalePromotionRequest', () => {
+  it('el parche vacío es válido y un campo mal tipado no', async () => {
+    expect(await errorPaths(UpdateSalePromotionRequest, {})).toHaveLength(0);
+    expect(await errorPaths(UpdateSalePromotionRequest, { appliesTo: PromotionAppliesToEnum.SUREKEEP_ONLY })).toHaveLength(0);
+    expect(await errorPaths(UpdateSalePromotionRequest, { budgetMaxCents: 10.5 })).toContain('budgetMaxCents');
+  });
+});
+
+describe('ChangeSalePromotionStatusRequest', () => {
+  it('acepta una transición del enum y rechaza un estado', async () => {
+    expect(await errorPaths(ChangeSalePromotionStatusRequest, { transition: SalePromotionTransitionEnum.PAUSE, reason: 'fin de stock' })).toHaveLength(0);
+    expect(await errorPaths(ChangeSalePromotionStatusRequest, { transition: 'ACTIVE' })).toContain('transition');
+  });
+});
+
+describe('queries paginadas', () => {
+  it('convierte limit del query string y lo acota', async () => {
+    const dto = plainToInstance(ListSalePromotionsQuery, { limit: '25', status: 'ARCHIVED' });
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.limit).toBe(25);
+    expect(await errorPaths(ListSalePromotionsQuery, { limit: '500' })).toContain('limit');
+  });
+
+  it('el log acepta formato CSV y rechaza otro', async () => {
+    expect(await errorPaths(ListSalePromotionLogQuery, { format: 'CSV', promotionId: 'p1' })).toHaveLength(0);
+    expect(await errorPaths(ListSalePromotionLogQuery, { format: 'XLSX' })).toContain('format');
+  });
+});