@fiado/type-kit 3.550.0 → 3.552.0

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

@@ -0,0 +1,48 @@
+import 'reflect-metadata';
+import * as RetailCatalog from '../../../src/retailCatalog';
+
+// ts-jest compila con type-check: si un campo sigue obligatorio o no existe, la suite no compila.
+describe('retailCatalog — un solo precio y valor del regalo', () => {
+  const reservation: RetailCatalog.ReserveStockResponse = {
+    expiresAt: '2026-10-20T20:30:00.000Z',
+    basePriceCents: 0,
+    priceSk: '2026-10-01T00:00:00.000Z',
+    eligibleFinanciers: [],
+    sellItemCost: 1,
+    mdmEnabled: false,
+    mdmProvider: null,
+  };
+
+  it('ReserveStockResponse es válida sin listPriceCents ni giftValueCents', () => {
+    expect(reservation.giftValueCents).toBeUndefined();
+    expect(reservation.listPriceCents).toBeUndefined();
+  });
+
+  it('la reserva de regalo trae giftValueCents', () => {
+    const gift: RetailCatalog.ReserveStockResponse = { ...reservation, giftValueCents: 35000 };
+    expect(gift.giftValueCents).toBe(35000);
+  });
+
+  it('acepta los dos nombres con el mismo valor mientras dure la transición', () => {
+    const gift: RetailCatalog.ReserveStockResponse = { ...reservation, giftValueCents: 35000, listPriceCents: 35000 };
+    expect(gift.listPriceCents).toBe(gift.giftValueCents);
+  });
+
+  it('Product es válido sin listPriceCents', () => {
+    const product: Pick<RetailCatalog.Product, 'sku' | 'basePriceCents' | 'listPriceCents'> = {
+      sku: 'SKU-1',
+      basePriceCents: 129900,
+    };
+    expect(product.listPriceCents).toBeUndefined();
+  });
+
+  it('SkuPriceEntry es válido sin listPriceCents', () => {
+    const entry: RetailCatalog.SkuPriceEntry = {
+      effectiveFrom: '2026-10-20T00:00:00.000Z',
+      basePriceCents: 129900,
+      source: RetailCatalog.PriceSourceEnum.BACKOFFICE,
+      createdBy: 'backoffice-user-1',
+    };
+    expect(entry.listPriceCents).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,168 @@
+import 'reflect-metadata';
+import * as RetailCommission from '../../../src/retailCommission';
+
+describe('retailCommission — enums de los pagos', () => {
+    it('expone los estados de un depósito', () => {
+        expect(Object.values(RetailCommission.CommissionPaymentStatusEnum)).toEqual([
+            'PENDING', 'ACCREDITED', 'FAILED', 'UNVERIFIED',
+        ]);
+    });
+
+    it('expone por qué un saldo necesita atención', () => {
+        expect(Object.values(RetailCommission.CommissionPaymentAttentionEnum)).toEqual(['NO_WALLET', 'REJECTED', 'PAUSED', 'DEBT']);
+    });
+
+    it('expone los tipos de movimiento del libro', () => {
+        expect(Object.values(RetailCommission.CommissionLedgerMovementKindEnum)).toEqual([
+            'EARN', 'DEDUCT', 'RELEASE', 'PAID_OUTSIDE',
+        ]);
+    });
+
+    it('expone qué pide pagarle a un vendedor', () => {
+        expect(Object.values(RetailCommission.CommissionPayTriggerEnum)).toEqual([
+            'SALE', 'CUT', 'RELEASE', 'ADJUSTMENT', 'WALLET_LINKED', 'RETRY',
+        ]);
+    });
+});
+
+// Ana después del cierre del 12 de octubre: ganó $300, le descontaron $100 de una venta cancelada,
+// se le depositaron $180 y le quedan $20 de renta retenidos hasta el 1 de noviembre.
+const balance: RetailCommission.CommissionSellerBalance = {
+    retailerId: 'RET-1',
+    sellerId: 'V-01',
+    retainedCents: 2_000,
+    payableCents: 0,
+    inTransitCents: 0,
+    earnedCents: 30_000,
+    deductedCents: 10_000,
+    accreditedCents: 18_000,
+    paidOutsideCents: 0,
+    attention: null,
+    attentionCode: null,
+    attentionSince: null,
+    updatedAt: '2026-10-12T07:00:00.000Z',
+};
+
+const cut: RetailCommission.CommissionLedgerMovement = {
+    movementKey: 'MOV#2026-10-05#CUT',
+    kind: RetailCommission.CommissionLedgerMovementKindEnum.EARN,
+    periodId: '2026-10-05',
+    retainedDeltaCents: 2_000,
+    payableDeltaCents: 8_000,
+    byRule: [
+        { ruleId: 'RC-BASE', payTiming: RetailCommission.CommissionPayTimingEnum.ON_CUT, cents: 8_000 },
+        { ruleId: 'RC-RENTA', payTiming: RetailCommission.CommissionPayTimingEnum.MONTHLY, cents: 2_000 },
+    ],
+    saleId: null,
+    adjustmentId: null,
+    releaseMonth: null,
+    reason: null,
+    createdAt: '2026-10-12T06:00:00.000Z',
+    createdBy: 'system',
+};
+
+const accredited: RetailCommission.CommissionPayment = {
+    paymentId: '01JPAY0000000000000000001',
+    retailerId: 'RET-1',
+    sellerId: 'V-01',
+    amountCents: 10_000,
+    status: RetailCommission.CommissionPaymentStatusEnum.ACCREDITED,
+    directoryId: 'DIR-1',
+    transactionId: 'TX-1',
+    errorCode: null,
+    concept: 'Comisiones VentasLuga · 5 oct 2026',
+    requestedAt: '2026-10-05T18:00:00.000Z',
+    resolvedAt: '2026-10-05T18:00:02.000Z',
+    resolvedBy: null,
+    note: null,
+};
+
+const statement: RetailCommission.CommissionChainStatement = {
+    statementId: '01JSTMT00000000000000001',
+    retailerId: 'RET-1',
+    period: RetailCommission.CommissionBillingPeriodEnum.WEEKLY,
+    startDate: '2026-10-05',
+    endDate: '2026-10-11',
+    accreditedCents: 10_000,
+    paymentsCount: 1,
+    sellersCount: 1,
+    generatedAt: '2026-10-12T07:00:00.000Z',
+};
+
+describe('retailCommission — libro de pagos', () => {
+    it('lo que queda en las tres bolsas es lo ganado menos lo descontado, lo depositado y lo pagado por fuera', () => {
+        const inPockets = balance.retainedCents + balance.payableCents + balance.inTransitCents;
+        expect(inPockets).toBe(balance.earnedCents - balance.deductedCents - balance.accreditedCents - balance.paidOutsideCents);
+    });
+
+    it('el movimiento del cierre reparte por regla entre retenido y exigible', () => {
+        const total = cut.byRule.reduce((sum, r) => sum + r.cents, 0);
+        expect(total).toBe(cut.retainedDeltaCents + cut.payableDeltaCents);
+    });
+
+    it('un depósito confirmado trae folio y uno rechazado su código', () => {
+        const failed: RetailCommission.CommissionPayment = {
+            ...accredited,
+            paymentId: '01JPAY0000000000000000002',
+            status: RetailCommission.CommissionPaymentStatusEnum.FAILED,
+            transactionId: null,
+            errorCode: 'USER_NOT_ACTIVE',
+        };
+        expect([failed.transactionId, failed.errorCode]).toEqual([null, 'USER_NOT_ACTIVE']);
+    });
+
+    it('el estado de cuenta cubre un periodo de cobro', () => {
+        expect([statement.period, statement.startDate, statement.endDate]).toEqual(['WEEKLY', '2026-10-05', '2026-10-11']);
+    });
+});
+
+describe('retailCommission — contratos de los pagos', () => {
+    it('"Por pagar" trae pendientes, depósitos sin confirmar y deudas', () => {
+        const unverified: RetailCommission.CommissionPayment = {
+            ...accredited,
+            status: RetailCommission.CommissionPaymentStatusEnum.UNVERIFIED,
+            transactionId: null,
+            resolvedAt: null,
+        };
+        const debt: RetailCommission.CommissionSellerBalance = {
+            ...balance,
+            payableCents: -5_000,
+            attention: RetailCommission.CommissionPaymentAttentionEnum.DEBT,
+            attentionSince: '2026-10-09T18:00:00.000Z',
+        };
+        const report: RetailCommission.GetPaymentAttentionResponse = { pending: [], unverified: [unverified], debts: [debt] };
+        expect([report.unverified[0]?.status, report.debts[0]?.attention]).toEqual(['UNVERIFIED', 'DEBT']);
+    });
+
+    it('pagado por fuera lleva motivo; la revisión manda folio solo si sí se depositó', () => {
+        const outside: RetailCommission.MarkPaidOutsideRequest = { amountCents: 8_000, reason: 'Pagado en efectivo en tienda' };
+        const yes: RetailCommission.ResolvePaymentRequest = { accredited: true, transactionId: 'TX-9', note: 'Folio confirmado' };
+        const no: RetailCommission.ResolvePaymentRequest = { accredited: false, note: 'No llegó a la wallet' };
+        expect([outside.amountCents, yes.transactionId, no.transactionId]).toEqual([8_000, 'TX-9', undefined]);
+    });
+
+    it('el historial del vendedor y los estados de cuenta de la cadena', () => {
+        const ledger: RetailCommission.GetSellerLedgerResponse = { balance, movements: [cut], payments: [accredited] };
+        const list: RetailCommission.ListStatementsResponse = { statements: [statement] };
+        const detail: RetailCommission.GetStatementResponse = { statement, payments: [accredited] };
+        expect([ledger.movements.length, list.statements.length, detail.payments.length]).toEqual([1, 1, 1]);
+    });
+
+    it('el vendedor sin nada en el libro ve su saldo en null', () => {
+        const mine: RetailCommission.GetMyPaymentsResponse = { balance: null, payments: [] };
+        expect(mine.balance).toBeNull();
+    });
+
+    it('las respuestas de las acciones de "Por pagar" y del aviso privado de wallet vinculada', () => {
+        const retry: RetailCommission.RetrySellerPaymentView = { sellerId: 'V-01', triggerId: '01JRETRY0000000000000000001' };
+        const outside: RetailCommission.MarkPaidOutsideView = { balance, movement: cut };
+        const resolved: RetailCommission.ResolvePaymentView = { payment: accredited };
+        const trigger: RetailCommission.PrivateTriggerSellerPaymentResponse = { enqueued: false };
+        expect([retry.sellerId, outside.movement.movementKey, resolved.payment.status, trigger.enqueued]).toEqual([
+            'V-01',
+            'MOV#2026-10-05#CUT',
+            'ACCREDITED',
+            false,
+        ]);
+    });
+});

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

@@ -28,6 +28,14 @@ describe('retailCommission — enums de las reglas', () => {
         expect(Object.values(RetailCommission.CommissionCountByEnum)).toEqual(['PIECE', 'SALE']);
     });
 
+    it('una regla se paga al momento, al cierre de la semana o al cierre del mes', () => {
+        expect(Object.values(RetailCommission.CommissionPayTimingEnum)).toEqual(['ON_SALE', 'ON_CUT', 'MONTHLY']);
+    });
+
+    it('a la cadena se le cobra cada semana o cada mes', () => {
+        expect(Object.values(RetailCommission.CommissionBillingPeriodEnum)).toEqual(['WEEKLY', 'MONTHLY']);
+    });
+
     it('expone las ventanas del corte', () => {
         expect(Object.values(RetailCommission.CommissionWindowEnum)).toEqual(['SEMANA_OPERATIVA', 'ROLLING_7D', 'MES']);
     });
@@ -99,6 +107,12 @@ describe('retailCommission — regla, políticas y snapshot', () => {
         expect(npi.condition?.minSample).toBe(5);
     });
 
+    it('la regla dice cuándo se paga, y una sin el campo sigue siendo válida', () => {
+        const monthly: RetailCommission.CommissionRule = { ...base, payTiming: RetailCommission.CommissionPayTimingEnum.MONTHLY };
+        expect(base.payTiming).toBeUndefined();
+        expect(monthly.payTiming).toBe('MONTHLY');
+    });
+
     it('el snapshot congela las reglas publicadas y las políticas', () => {
         const snapshot: RetailCommission.CommissionRuleSetSnapshot = {
             retailerId: 'RET-1',
@@ -124,6 +138,17 @@ describe('retailCommission — regla, políticas y snapshot', () => {
         const policies: RetailCommission.CommissionPolicies = { clawback: null, commissions: null };
         expect(policies.clawback).toBeNull();
     });
+
+    it('la política de pagos es opcional y viaja con las demás', () => {
+        const payouts: RetailCommission.CommissionPayoutPolicy = {
+            walletDeposits: false,
+            chainBillingPeriod: RetailCommission.CommissionBillingPeriodEnum.MONTHLY,
+        };
+        const legacy: RetailCommission.CommissionPolicies = { clawback: null, commissions: null };
+        const withPayouts: RetailCommission.CommissionPolicies = { ...legacy, payouts };
+        expect(legacy.payouts).toBeUndefined();
+        expect(withPayouts.payouts?.chainBillingPeriod).toBe('MONTHLY');
+    });
 });
 
 describe('retailCommission — devengo con reglas', () => {
@@ -234,6 +259,23 @@ describe('retailCommission — contratos de reglas y políticas', () => {
         expect([create.name, update.expectedVersion, action.expectedVersion]).toEqual(['Bono Accesorios', 2, 3]);
     });
 
+    it('el editor manda cuándo se paga y el vendedor lo ve', () => {
+        const create: RetailCommission.CreateRuleRequest = { ...input, payTiming: RetailCommission.CommissionPayTimingEnum.ON_SALE };
+        const view: RetailCommission.CommissionRuleView = {
+            ruleId: 'RC-01',
+            name: create.name,
+            description: create.description,
+            levers: create.levers,
+            scope: create.scope,
+            condition: create.condition,
+            effectiveFrom: create.effectiveFrom,
+            effectiveTo: create.effectiveTo,
+            payTiming: create.payTiming,
+        };
+        expect(input.payTiming).toBeUndefined();
+        expect(view.payTiming).toBe('ON_SALE');
+    });
+
     it('las políticas se guardan juntas', () => {
         const request: RetailCommission.UpdatePoliciesRequest = {
             clawback: { cancelacionDias: 7, devolucionDias: 7, npiM30Dias: 30 },
@@ -242,6 +284,17 @@ describe('retailCommission — contratos de reglas y políticas', () => {
         expect(request.commissions.multiplicadorMaxBps).toBe(25000);
     });
 
+    it('la política de pagos se guarda con las demás, y un editor que no la manda sigue siendo válido', () => {
+        const request: RetailCommission.UpdatePoliciesRequest = {
+            clawback: { cancelacionDias: 7, devolucionDias: 7, npiM30Dias: 30 },
+            commissions: { multiplicadorMaxBps: 25000, ventanaDefault: CommissionWindowEnum.SEMANA_OPERATIVA },
+            payouts: { walletDeposits: true, chainBillingPeriod: RetailCommission.CommissionBillingPeriodEnum.WEEKLY },
+        };
+        const legacy: RetailCommission.UpdatePoliciesRequest = { clawback: request.clawback, commissions: request.commissions };
+        expect(request.payouts?.walletDeposits).toBe(true);
+        expect(legacy.payouts).toBeUndefined();
+    });
+
     it('el plan vigente con reglas puede no existir todavía', () => {
         const response: RetailCommission.GetRuleSetResponse = { active: null };
         const history: RetailCommission.RuleHistoryResponse = {

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

@@ -94,6 +94,7 @@ describe('ProductEventPayload', () => {
         ['price.effectiveFrom', { price: { ...product.price, effectiveFrom: '2026-08-17T20:32:05' } }],
         ['eligibleFinanciers', { eligibleFinanciers: ['NADIE'] }],
         ['tier', { tier: undefined }],
+        ['price.listPrice', { price: { basePrice: '4299.00', effectiveFrom: '2026-08-17T20:32:05Z' } }],
     ])('rechaza %s', async (path, over) => {
         expect(await errorsOf(ProductEventPayload, { ...product, ...over })).toContain(path);
     });

package/_test_/unit/retailOrg/dtos/RetailUser.test.ts

@@ -5,6 +5,7 @@ import { RetailUser } from '../../../../src/retailOrg/dtos/RetailUser';
 import { EmploymentTypeEnum } from '../../../../src/retailOrg/enums/EmploymentTypeEnum';
 import { RetailUserStatusEnum } from '../../../../src/retailOrg/enums/RetailUserStatusEnum';
 import { CollectorSeniorityEnum } from '../../../../src/retailOrg/enums/CollectorSeniorityEnum';
+import { RetailUserWalletLinkMethodEnum } from '../../../../src/retailOrg/enums/RetailUserWalletLinkMethodEnum';
 
 const valid = {
     retailUserId: 'ru_001',
@@ -82,3 +83,49 @@ describe('RetailUser', () => {
         expect(errors.some(e => e.property === 'cognitoSub')).toBe(true);
     });
 });
+
+describe('RetailUser — wallet PCF', () => {
+    const linked = {
+        ...valid,
+        fiadoDirectoryId: 'dir_001',
+        pcfAccountId: 'pcf_001',
+        walletLinkMethod: RetailUserWalletLinkMethodEnum.CLABE,
+        walletClabeLast4: '9012',
+        walletLinkedAt: '2026-10-20T10:00:00.000Z',
+        walletLinkedBy: 'admin_001',
+    };
+
+    it('valida con la wallet vinculada', async () => {
+        const errors = await validate(plainToInstance(RetailUser, linked));
+        expect(errors).toEqual([]);
+    });
+
+    it('valida con la wallet desvinculada (campos en null)', async () => {
+        const unlinked = {
+            ...valid,
+            fiadoDirectoryId: null,
+            pcfAccountId: null,
+            walletLinkMethod: null,
+            walletClabeLast4: null,
+            walletLinkedAt: null,
+            walletLinkedBy: null,
+        };
+        const errors = await validate(plainToInstance(RetailUser, unlinked));
+        expect(errors).toEqual([]);
+    });
+
+    it('falla si walletLinkMethod está fuera del enum', async () => {
+        const errors = await validate(plainToInstance(RetailUser, { ...linked, walletLinkMethod: 'EMAIL' }));
+        expect(errors.some(e => e.property === 'walletLinkMethod')).toBe(true);
+    });
+
+    it('falla si walletClabeLast4 trae la CLABE completa', async () => {
+        const errors = await validate(plainToInstance(RetailUser, { ...linked, walletClabeLast4: '646180123456789012' }));
+        expect(errors.some(e => e.property === 'walletClabeLast4')).toBe(true);
+    });
+
+    it('falla si walletLinkedAt no es ISO 8601', async () => {
+        const errors = await validate(plainToInstance(RetailUser, { ...linked, walletLinkedAt: '20/10/2026' }));
+        expect(errors.some(e => e.property === 'walletLinkedAt')).toBe(true);
+    });
+});

package/_test_/unit/retailOrg/dtos/requests/retailUserWalletRequests.test.ts

@@ -0,0 +1,41 @@
+import 'reflect-metadata';
+import { plainToInstance, type ClassConstructor } from 'class-transformer';
+import { validateSync, type ValidationError } from 'class-validator';
+import { LinkRetailUserWalletRequest, LookupRetailUserWalletRequest } from '../../../../../src/retailOrg';
+
+const CLABE = '646180123456789012';
+const PHONE = '+525512345678';
+
+function validate(cls: ClassConstructor<object>, payload: object): ValidationError[] {
+    return validateSync(plainToInstance(cls, payload, { excludeExtraneousValues: true }));
+}
+
+function errorsOf(cls: ClassConstructor<object>, payload: object): string[] {
+    return validate(cls, payload).map((e) => e.property);
+}
+
+function clabeConstraints(cls: ClassConstructor<object>, payload: object): string[] {
+    return Object.keys(validate(cls, payload).find((e) => e.property === 'clabe')?.constraints ?? {});
+}
+
+const requests: Array<[string, ClassConstructor<object>]> = [
+    ['LookupRetailUserWalletRequest', LookupRetailUserWalletRequest],
+    ['LinkRetailUserWalletRequest', LinkRetailUserWalletRequest],
+];
+
+describe.each(requests)('%s', (_name, cls) => {
+    it('acepta solo la CLABE', () => expect(errorsOf(cls, { clabe: CLABE })).toEqual([]));
+    it('acepta solo el teléfono', () => expect(errorsOf(cls, { phone: PHONE })).toEqual([]));
+    it('rechaza la CLABE y el teléfono juntos', () => expect(errorsOf(cls, { clabe: CLABE, phone: PHONE })).toContain('clabe'));
+    it('rechaza un body sin ninguno', () => expect(clabeConstraints(cls, {})).toContain('isSingleWalletKey'));
+    it('rechaza un teléfono en null sin CLABE', () =>
+        expect(clabeConstraints(cls, { phone: null })).toContain('isSingleWalletKey'));
+    it('acepta la CLABE en null con teléfono', () => expect(errorsOf(cls, { clabe: null, phone: '5512345678' })).toEqual([]));
+    it('rechaza la CLABE vacía con teléfono', () => expect(errorsOf(cls, { clabe: '', phone: '5512345678' })).toContain('clabe'));
+    it('rechaza una CLABE que no son 18 dígitos', () => expect(errorsOf(cls, { clabe: '64618012345678901' })).toContain('clabe'));
+    it('acepta el teléfono en 10 dígitos, sin +52', () => expect(errorsOf(cls, { phone: '5512345678' })).toEqual([]));
+    it('rechaza un teléfono que no son 10 dígitos o que trae otra lada', () => {
+        expect(errorsOf(cls, { phone: '551234567' })).toContain('phone');
+        expect(errorsOf(cls, { phone: '+15512345678' })).toContain('phone');
+    });
+});

package/_test_/unit/retailOrg/dtos/responses/retailUserWalletResponses.test.ts

@@ -0,0 +1,30 @@
+import 'reflect-metadata';
+import {
+    RetailUserWalletLinkMethodEnum,
+    type LookupRetailUserWalletResponse,
+    type PrivateRetailUserWalletResponse,
+} from '../../../../../src/retailOrg';
+
+describe('respuestas de la wallet del vendedor', () => {
+    it('la búsqueda dice si la encontró, si está activa y a nombre de quién', () => {
+        const found: LookupRetailUserWalletResponse = {
+            found: true,
+            active: true,
+            holderName: 'Ana López',
+            method: RetailUserWalletLinkMethodEnum.CLABE,
+        };
+        const missing: LookupRetailUserWalletResponse = {
+            found: false,
+            active: false,
+            holderName: null,
+            method: RetailUserWalletLinkMethodEnum.PHONE,
+        };
+        expect([found.holderName, missing.holderName]).toEqual(['Ana López', null]);
+    });
+
+    it('el privado devuelve la wallet o null si no tiene', () => {
+        const linked: PrivateRetailUserWalletResponse = { directoryId: 'dir_001', pcfAccountId: 'pcf_001' };
+        const none: PrivateRetailUserWalletResponse = { directoryId: null, pcfAccountId: null };
+        expect([linked.directoryId, none.directoryId]).toEqual(['dir_001', null]);
+    });
+});

package/_test_/unit/retailOrg/enums/RetailUserWalletLinkMethodEnum.test.ts

@@ -0,0 +1,12 @@
+import { RetailUserWalletLinkMethodEnum } from '../../../../src/retailOrg/enums/RetailUserWalletLinkMethodEnum';
+
+describe('RetailUserWalletLinkMethodEnum', () => {
+    it('contiene exactamente los métodos del contrato con value === key', () => {
+        expect(RetailUserWalletLinkMethodEnum.CLABE).toBe('CLABE');
+        expect(RetailUserWalletLinkMethodEnum.PHONE).toBe('PHONE');
+    });
+
+    it('no tiene valores de más', () => {
+        expect(Object.values(RetailUserWalletLinkMethodEnum).sort()).toEqual(['CLABE', 'PHONE']);
+    });
+});

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

@@ -0,0 +1,20 @@
+import 'reflect-metadata';
+import type { GiftOption } from '../../../src/retailPromotions/index';
+
+describe('GiftOption.valueCents', () => {
+  it('trae el valor del regalo sin listPriceCents', () => {
+    const option: GiftOption = { sku: 'CASE-1', name: 'Funda', valueCents: 35000, inStock: true };
+    expect(option.valueCents).toBe(35000);
+    expect(option.listPriceCents).toBeUndefined();
+  });
+
+  it('acepta los dos nombres con el mismo valor mientras dure la transición', () => {
+    const option: GiftOption = { sku: 'CASE-1', name: 'Funda', valueCents: 35000, listPriceCents: 35000, inStock: true };
+    expect(option.listPriceCents).toBe(option.valueCents);
+  });
+
+  it('sigue aceptando solo el nombre viejo, para no romper a promotions develop', () => {
+    const legacy: GiftOption = { sku: 'CASE-1', name: 'Funda', listPriceCents: 35000, inStock: true };
+    expect(legacy.valueCents).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,40 @@
+import 'reflect-metadata';
+import {
+  LinePaymentTypeEnum,
+  WizardLineStatusEnum,
+  type SaleLine,
+  type WizardReservedLine,
+} from '../../../src/retailWizard';
+
+describe('retailWizard — líneas sin precio de lista', () => {
+  it('WizardReservedLine es válida sin listPriceCents', () => {
+    const line: WizardReservedLine = {
+      lineId: 'L1',
+      sku: 'PHONE-1',
+      qty: 1,
+      status: WizardLineStatusEnum.RESERVED,
+      reservationId: 'r-1',
+      expiresAt: '2026-10-20T20:30:00.000Z',
+      basePriceCents: 349900,
+      priceSk: 'p',
+      eligibleFinanciers: ['SUREKEEP'],
+      financeable: true,
+      paymentType: LinePaymentTypeEnum.CREDIT,
+      sellItemCost: 1,
+    };
+    expect(line.listPriceCents).toBeUndefined();
+  });
+
+  it('SaleLine es válida sin listPriceCents', () => {
+    const line: SaleLine = {
+      lineId: 'L1',
+      sku: 'PHONE-1',
+      qty: 1,
+      basePriceCents: 349900,
+      priceSk: 'p',
+      paymentType: LinePaymentTypeEnum.CREDIT,
+      components: [{ sku: 'PHONE-1', qty: 1, identifiers: ['356938035643809'] }],
+    };
+    expect(line.listPriceCents).toBeUndefined();
+  });
+});

package/bin/retailCatalog/dtos/Product.d.ts

@@ -27,7 +27,8 @@ export declare class Product {
     /** `null` = Sin gama. */
     tier: ProductTierEnum | null;
     basePriceCents: number;
-    listPriceCents: number | null;
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
+    listPriceCents?: number | null;
     eligibleFinanciers: string[];
     mdmEnabled: boolean;
     mdmProvider: MdmProviderEnum | null;

package/bin/retailCatalog/dtos/requests/BackofficeCreateSkuPriceRequest.d.ts

@@ -1,5 +1,6 @@
 /** Body de POST /backoffice/inventory/skus/{sku}/prices (backofficeCreateSkuPrice); crea un PRICE# nuevo con origen BACKOFFICE. */
 export declare class BackofficeCreateSkuPriceRequest {
     basePriceCents: number;
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
     listPriceCents?: number | null;
 }

package/bin/retailCatalog/dtos/requests/CreateProductRequest.d.ts

@@ -17,6 +17,7 @@ export declare class CreateProductRequest {
     imageUrl?: string | null;
     tier: ProductTierEnum;
     basePriceCents: number;
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
     listPriceCents?: number | null;
     eligibleFinanciers: string[];
     mdmEnabled: boolean;

package/bin/retailCatalog/dtos/requests/SyncInventoryRequest.d.ts

@@ -6,6 +6,7 @@ import { TrackingModeEnum } from '../../enums/TrackingModeEnum';
 import { ProductComponent } from '../ProductComponent';
 /** Precio de un producto en la puerta de entrada; crea PRICE# solo si cambió el monto. */
 export declare class SyncPrice {
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
     listPriceCents?: number | null;
     basePriceCents: number;
     effectiveFrom: string;

package/bin/retailCatalog/dtos/requests/UpdateProductRequest.d.ts

@@ -16,6 +16,7 @@ export declare class UpdateProductRequest {
     imageUrl?: string | null;
     tier?: ProductTierEnum;
     basePriceCents?: number;
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
     listPriceCents?: number | null;
     eligibleFinanciers?: string[];
     mdmEnabled?: boolean;

package/bin/retailCatalog/dtos/responses/InventoryLensResponse.d.ts

@@ -61,7 +61,7 @@ export interface InventoryLensSkuItem {
     criticalStock: boolean;
     /** Unidades de este SKU vendidas hoy en esta tienda, **financiadas por SureKeep**. */
     soldTodayUnits: number;
-    /** Precio de contado en centavos (`listPriceCents`, o `basePriceCents` si no hay lista). */
+    /** Precio de contado en centavos (`basePriceCents`). */
     cashPriceCents: number;
 }
 /** Una fila del tab `transfers`: mover unidades de un SKU de una tienda con excedente a una en crítico. */

package/bin/retailCatalog/dtos/responses/ReserveStockResponse.d.ts

@@ -14,7 +14,10 @@ export interface ReservedComponent {
 export interface ReserveStockResponse {
     expiresAt: string;
     basePriceCents: number;
-    listPriceCents: number | null;
+    /** @deprecated Usa `giftValueCents`; en reservas GIFT trae el mismo valor, en las demás `null`. */
+    listPriceCents?: number | null;
+    /** Solo en reservas `purpose: GIFT`: valor del regalo, su precio de venta. */
+    giftValueCents?: number;
     /** Llave del registro PRICE# del que salió el precio fijado. */
     priceSk: string;
     eligibleFinanciers: string[];

package/bin/retailCatalog/dtos/responses/SkuPriceEntry.d.ts

@@ -2,7 +2,8 @@ import type { PriceSourceEnum } from '../../enums/PriceSourceEnum';
 /** Un registro del historial de precios PRICE# de un SKU. */
 export interface SkuPriceEntry {
     effectiveFrom: string;
-    listPriceCents: number | null;
+    /** @deprecated Ya no se usa; el único precio es `basePriceCents`. */
+    listPriceCents?: number | null;
     basePriceCents: number;
     source: PriceSourceEnum;
     createdBy: string;

package/bin/retailCatalog/dtos/responses/StoreCatalogItem.d.ts

@@ -36,7 +36,7 @@ export interface StoreCatalogItem {
     itemType?: ItemTypeEnum;
     /** Nombre visible para kits y servicios, que no tienen marca/modelo. */
     description?: string;
-    /** Precio de lista de respaldo para un regalo: el precio vigente o, si no hay, product.basePriceCents. */
+    /** @deprecated Ya no se usa; el valor de un regalo es `basePriceCents`. */
     listPriceCents?: number;
     /** Prioridad de venta de 0 a 100; «Recomendados» ordena por ella. */
     salePriority?: number;