@fiado/type-kit 3.563.0 → 3.565.0

package/_test_/unit/retailCustomer/customerReferralContract.test.ts

@@ -0,0 +1,228 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { ValidationError, validateSync } from 'class-validator';
+import { RetailCustomer } from '../../../src/index';
+import {
+    AccountStatusEnum,
+    CreateCustomerReferralsRequest,
+    CustomerReferral,
+    GetCustomersByPhonesRequest,
+    GetReferralsByPhoneQuery,
+    ReferralRoleEnum,
+    ReferralSourceEnum,
+    ReferralStatusEnum,
+    UpdateCustomerReferralRequest,
+    UpsertPromotionBonusRequest,
+} from '../../../src/retailCustomer/index';
+import type {
+    CreateCustomerReferralsResponse,
+    CustomersByPhonesResponse,
+    ListCustomerReferralsResponse,
+    ReferralsByPhoneResponse,
+    UpdateCustomerReferralResponse,
+} from '../../../src/retailCustomer/index';
+
+/** Rutas `propiedad` o `lista.0.propiedad` de los errores, como las lee el lambda para armar el renglón. */
+function pathsOf(errors: ValidationError[], prefix = ''): string[] {
+    return errors.flatMap((e) => {
+        const path = `${prefix}${e.property}`;
+        return e.children && e.children.length > 0 ? pathsOf(e.children, `${path}.`) : [path];
+    });
+}
+
+function errorsOf<T extends object>(cls: new () => T, payload: Record<string, unknown>): string[] {
+    const dto = plainToInstance(cls, payload, { excludeExtraneousValues: true });
+    return pathsOf(validateSync(dto));
+}
+
+describe('enums de referidos', () => {
+    it('ReferralSourceEnum distingue venta, apertura y cajón', () => {
+        expect(Object.values(ReferralSourceEnum)).toEqual(['SALE', 'OPENING', 'BACKOFFICE']);
+    });
+
+    it('ReferralStatusEnum trae los cuatro estados del cajón', () => {
+        expect(Object.values(ReferralStatusEnum)).toEqual([
+            'NOT_PURCHASED',
+            'ACCOUNT_OPENED',
+            'PURCHASED',
+            'SUREKEEP_CREDIT',
+        ]);
+    });
+
+    it('ReferralRoleEnum distingue a quien recomienda del recomendado', () => {
+        expect(Object.values(ReferralRoleEnum)).toEqual(['REFERRER', 'REFERRED']);
+    });
+
+    it('salen por el index raíz', () => {
+        expect(RetailCustomer.ReferralSourceEnum.BACKOFFICE).toBe('BACKOFFICE');
+        expect(new RetailCustomer.CreateCustomerReferralsRequest()).toBeInstanceOf(CreateCustomerReferralsRequest);
+    });
+});
+
+const SALE_BATCH = {
+    source: 'SALE',
+    storeId: 'st-1',
+    wizardSessionId: 'ws-1',
+    capturedBy: 'seller-1',
+    referrals: [{ name: 'Ana López', phone: '55 1234 5678' }],
+};
+
+describe('CreateCustomerReferralsRequest', () => {
+    it('acepta un lote de la venta con correo opcional ausente', () => {
+        expect(errorsOf(CreateCustomerReferralsRequest, SALE_BATCH)).toEqual([]);
+    });
+
+    it('acepta el correo cuando viene', () => {
+        const referrals = [{ name: 'Ana', phone: '5512345678', email: 'ana@correo.mx' }];
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...SALE_BATCH, referrals })).toEqual([]);
+    });
+
+    it('marca el renglón y el campo que faltan', () => {
+        const referrals = [{ name: 'Ana', phone: '5512345678' }, { name: '  ', phone: '' }];
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...SALE_BATCH, referrals })).toEqual([
+            'referrals.1.name',
+            'referrals.1.phone',
+        ]);
+    });
+
+    it('rechaza un correo inválido en su renglón', () => {
+        const referrals = [{ name: 'Ana', phone: '5512345678', email: 'no-es-correo' }];
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...SALE_BATCH, referrals })).toEqual(['referrals.0.email']);
+    });
+
+    it('rechaza el lote vacío', () => {
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...SALE_BATCH, referrals: [] })).toContain('referrals');
+    });
+
+    it('exige quién capturó, sin default', () => {
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...SALE_BATCH, capturedBy: ' ' })).toContain('capturedBy');
+    });
+
+    it('rechaza un origen fuera del catálogo', () => {
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...SALE_BATCH, source: 'WEB' })).toContain('source');
+    });
+
+    it('venta y apertura exigen la tienda; el cajón no', () => {
+        const { storeId: _storeId, ...noStore } = SALE_BATCH;
+        expect(errorsOf(CreateCustomerReferralsRequest, noStore)).toContain('storeId');
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...noStore, source: 'OPENING' })).toContain('storeId');
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...noStore, source: 'BACKOFFICE' })).toEqual([]);
+    });
+});
+
+describe('UpdateCustomerReferralRequest', () => {
+    it('acepta corregir solo el teléfono', () => {
+        expect(errorsOf(UpdateCustomerReferralRequest, { phone: '5512345678', updatedBy: 'admin-1' })).toEqual([]);
+    });
+
+    it('acepta quitar el correo con null', () => {
+        expect(errorsOf(UpdateCustomerReferralRequest, { email: null, updatedBy: 'admin-1' })).toEqual([]);
+    });
+
+    it('rechaza vaciar el nombre o el teléfono', () => {
+        const errors = errorsOf(UpdateCustomerReferralRequest, { name: ' ', phone: '', updatedBy: 'admin-1' });
+        expect(errors).toEqual(['name', 'phone']);
+    });
+
+    it('exige quién edita', () => {
+        expect(errorsOf(UpdateCustomerReferralRequest, { name: 'Ana' })).toContain('updatedBy');
+    });
+});
+
+describe('GetCustomersByPhonesRequest', () => {
+    it('acepta un lote de teléfonos', () => {
+        expect(errorsOf(GetCustomersByPhonesRequest, { phones: ['5512345678', '5587654321'] })).toEqual([]);
+    });
+
+    it('rechaza el lote vacío o de más de 100', () => {
+        expect(errorsOf(GetCustomersByPhonesRequest, { phones: [] })).toContain('phones');
+        const many = Array.from({ length: 101 }, (_, i) => String(5500000000 + i));
+        expect(errorsOf(GetCustomersByPhonesRequest, { phones: many })).toContain('phones');
+    });
+});
+
+describe('GetReferralsByPhoneQuery', () => {
+    it('acepta cadena y teléfono, con el corte opcional', () => {
+        expect(errorsOf(GetReferralsByPhoneQuery, { retailerId: 'r-1', phone: '5512345678' })).toEqual([]);
+        expect(
+            errorsOf(GetReferralsByPhoneQuery, { retailerId: 'r-1', phone: '5512345678', before: '2026-10-21T10:00:00Z' }),
+        ).toEqual([]);
+    });
+
+    it('rechaza un corte que no es fecha ISO', () => {
+        expect(errorsOf(GetReferralsByPhoneQuery, { retailerId: 'r-1', phone: '5512345678', before: 'ayer' })).toEqual([
+            'before',
+        ]);
+    });
+});
+
+describe('CustomerReferral y respuestas', () => {
+    const referral: CustomerReferral = {
+        referralId: 'ref-1',
+        retailCustomerId: 'c-1',
+        retailerId: 'r-1',
+        storeId: 'st-1',
+        name: 'Ana López',
+        phone: '5512345678',
+        email: null,
+        source: ReferralSourceEnum.SALE,
+        wizardSessionId: 'ws-1',
+        saleId: 'sale-1',
+        accountOpeningSessionId: null,
+        createdBy: 'seller-1',
+        updatedBy: 'seller-1',
+        createdAt: '2026-10-21T10:00:00Z',
+        updatedAt: '2026-10-21T10:00:00Z',
+    };
+
+    it('valida la entidad con @Expose', () => {
+        expect(errorsOf(CustomerReferral, { ...referral })).toEqual([]);
+        expect(errorsOf(CustomerReferral, { ...referral, source: 'WEB' })).toEqual(['source']);
+    });
+
+    it('describe las respuestas de las rutas privadas', () => {
+        const created: CreateCustomerReferralsResponse = { referrals: [referral] };
+        const updated: UpdateCustomerReferralResponse = { referral };
+        const listed: ListCustomerReferralsResponse = { referrals: [referral] };
+        const byPhone: ReferralsByPhoneResponse = {
+            referrals: [
+                {
+                    referralId: 'ref-1',
+                    referrerCustomerId: 'c-1',
+                    referrerName: 'Juan Pérez',
+                    source: ReferralSourceEnum.SALE,
+                    capturedAt: '2026-10-21T10:00:00Z',
+                },
+            ],
+        };
+        const customers: CustomersByPhonesResponse = {
+            customers: [{ phone: '5512345678', retailCustomerId: 'c-9', retailerId: 'r-1', accountStatus: AccountStatusEnum.OPEN }],
+        };
+        expect([created, updated, listed, byPhone, customers]).toHaveLength(5);
+    });
+});
+
+describe('UpsertPromotionBonusRequest con referido', () => {
+    const PENDING_SALE = {
+        bonusType: 'SALE_PROMOTION',
+        promotionId: 'promo-1',
+        sourceId: 'sale-1',
+        storeId: 'st-1',
+        amountCents: 10_000,
+        currency: 'MXN',
+        status: 'PENDING',
+        idempotencyKey: 'sale-1-WALLET-1',
+    };
+
+    it('acepta rol y referralId opcionales', () => {
+        expect(errorsOf(UpsertPromotionBonusRequest, PENDING_SALE)).toEqual([]);
+        expect(
+            errorsOf(UpsertPromotionBonusRequest, { ...PENDING_SALE, role: 'REFERRER', referralId: 'ref-1' }),
+        ).toEqual([]);
+    });
+
+    it('rechaza un rol fuera del catálogo o un referralId vacío', () => {
+        expect(errorsOf(UpsertPromotionBonusRequest, { ...PENDING_SALE, role: 'SELLER' })).toEqual(['role']);
+        expect(errorsOf(UpsertPromotionBonusRequest, { ...PENDING_SALE, referralId: ' ' })).toEqual(['referralId']);
+    });
+});

package/_test_/unit/retailCustomer/welcomeBonusRequests.test.ts

@@ -219,6 +219,6 @@ describe('enums del bono de bienvenida', () => {
     });
 
     it('el origen del monto distingue el parámetro del fallback local', () => {
-        expect(Object.values(WelcomeBonusAmountSourceEnum)).toEqual(['PARAM', 'DEFAULT']);
+        expect(Object.values(WelcomeBonusAmountSourceEnum)).toEqual(['PARAM', 'DEFAULT', 'SALE_PROMOTION']);
     });
 });

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

@@ -43,7 +43,7 @@ describe('catálogo de errores', () => {
     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(32);
+    expect(Object.keys(RetailPromotionsErrorCodeEnum)).toHaveLength(36);
     expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS.SPLIT_FINANCING_DISABLED).toBe(409);
   });
 

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

@@ -0,0 +1,177 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { ValidationError, validateSync } from 'class-validator';
+import { RetailPromotions } from '../../../src/index';
+import {
+    CreateSalePromotionRequest,
+    ListSalePromotionsQuery,
+    RETAIL_PROMOTIONS_ERROR_HTTP_STATUS,
+    ReferralPromotionChannelEnum,
+    ReferralPromotionInput,
+    ReferralRewardTypeEnum,
+    ReferralTriggerEnum,
+    RetailPromotionsErrorCodeEnum,
+    SalePromotionKindEnum,
+    UpdateSalePromotionRequest,
+} from '../../../src/retailPromotions/index';
+import type { ReferralPromotionConfig, SalePromotion } from '../../../src/retailPromotions/index';
+
+function pathsOf(errors: ValidationError[], prefix = ''): string[] {
+    return errors.flatMap((e) => {
+        const path = `${prefix}${e.property}`;
+        return e.children && e.children.length > 0 ? pathsOf(e.children, `${path}.`) : [path];
+    });
+}
+
+const errorsOf = <T extends object>(cls: new () => T, payload: Record<string, unknown>): string[] =>
+    pathsOf(validateSync(plainToInstance(cls, payload, { excludeExtraneousValues: true })));
+
+describe('enums de promos de referido', () => {
+    it('SalePromotionKindEnum suma REFERRAL', () => {
+        expect(Object.values(SalePromotionKindEnum)).toEqual(['GIFT', 'SALE', 'REFERRAL']);
+    });
+
+    it('canal de venta o de crédito', () => {
+        expect(Object.values(ReferralPromotionChannelEnum)).toEqual(['SALE', 'CREDIT']);
+    });
+
+    it('los 7 eventos del referido', () => {
+        expect(Object.values(ReferralTriggerEnum)).toEqual([
+            'FIRST_PURCHASE',
+            'ACCOUNT_OPENED',
+            'ANY_PURCHASE',
+            'NTH_PURCHASE',
+            'CREDIT_ACTIVATED',
+            'FIRST_INSTALLMENT',
+            'INSTALLMENT_STREAK',
+        ]);
+    });
+
+    it('bono fijo, % con tope, cupón y descuento en la venta', () => {
+        expect(Object.values(ReferralRewardTypeEnum)).toEqual(['FIXED_BONUS', 'PERCENT_BONUS', 'COUPON', 'SALE_DISCOUNT']);
+    });
+
+    it('codes de validación de la promo de referido', () => {
+        expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS[RetailPromotionsErrorCodeEnum.REFERRAL_REWARD_NEEDS_PURCHASE]).toBe(422);
+        expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS[RetailPromotionsErrorCodeEnum.INVALID_REFERRAL_TRIGGER]).toBe(400);
+    });
+
+    it('salen por el index raíz', () => {
+        expect(RetailPromotions.ReferralTriggerEnum.INSTALLMENT_STREAK).toBe('INSTALLMENT_STREAK');
+        expect(new RetailPromotions.ReferralPromotionInput()).toBeInstanceOf(ReferralPromotionInput);
+    });
+});
+
+const FIXED = { type: 'FIXED_BONUS', amountCents: 200_00 };
+const REFERRAL = {
+    channel: 'SALE',
+    trigger: 'FIRST_PURCHASE',
+    minAmountCents: 3_000_00,
+    windowDays: 30,
+    maxRewardsPerReferrer: 5,
+    referrerReward: FIXED,
+    referredReward: { type: 'SALE_DISCOUNT', percentBps: 1000, maxAmountCents: 500_00 },
+};
+
+describe('ReferralPromotionInput', () => {
+    it('acepta una promo de venta con premio para los dos', () => {
+        expect(errorsOf(ReferralPromotionInput, REFERRAL)).toEqual([]);
+    });
+
+    it('acepta una promo de crédito con racha y sin premio al recomendado', () => {
+        const credit = {
+            channel: 'CREDIT',
+            trigger: 'INSTALLMENT_STREAK',
+            installmentStreak: 3,
+            referrerReward: { type: 'PERCENT_BONUS', percentBps: 500, maxAmountCents: 300_00 },
+            referredReward: null,
+        };
+        expect(errorsOf(ReferralPromotionInput, credit)).toEqual([]);
+    });
+
+    it('acepta el cupón como premio de quien recomienda', () => {
+        const coupon = { type: 'PERCENTAGE', percentBps: 1500, validityDays: 30, scope: 'CHAIN' };
+        const referrerReward = { type: 'COUPON', coupon };
+        expect(errorsOf(ReferralPromotionInput, { ...REFERRAL, referrerReward })).toEqual([]);
+    });
+
+    it('exige canal, evento y premio de quien recomienda', () => {
+        expect(errorsOf(ReferralPromotionInput, {})).toEqual(['channel', 'trigger', 'referrerReward']);
+    });
+
+    it('exige el dato que corresponde a cada premio', () => {
+        expect(errorsOf(ReferralPromotionInput, { ...REFERRAL, referrerReward: { type: 'FIXED_BONUS' } })).toEqual([
+            'referrerReward.amountCents',
+        ]);
+        expect(errorsOf(ReferralPromotionInput, { ...REFERRAL, referrerReward: { type: 'PERCENT_BONUS' } })).toEqual([
+            'referrerReward.percentBps',
+        ]);
+        expect(errorsOf(ReferralPromotionInput, { ...REFERRAL, referrerReward: { type: 'COUPON' } })).toEqual([
+            'referrerReward.coupon',
+        ]);
+    });
+
+    it('rechaza un % fuera de 1..10000 y montos no positivos', () => {
+        const pct = { type: 'PERCENT_BONUS', percentBps: 10001, maxAmountCents: 0 };
+        expect(errorsOf(ReferralPromotionInput, { ...REFERRAL, referrerReward: pct })).toEqual([
+            'referrerReward.percentBps',
+            'referrerReward.maxAmountCents',
+        ]);
+    });
+
+    it('rechaza ventana, máximo y monto mínimo negativos o cero', () => {
+        const bad = { ...REFERRAL, minAmountCents: -1, windowDays: 0, maxRewardsPerReferrer: 0 };
+        expect(errorsOf(ReferralPromotionInput, bad)).toEqual(['minAmountCents', 'windowDays', 'maxRewardsPerReferrer']);
+    });
+
+    it('deja al lambda el mínimo de 2 en compra N y racha (INVALID_REFERRAL_TRIGGER)', () => {
+        const nth = { ...REFERRAL, trigger: 'NTH_PURCHASE', purchaseNumber: 1 };
+        expect(errorsOf(ReferralPromotionInput, nth)).toEqual([]);
+        expect(errorsOf(ReferralPromotionInput, { ...nth, purchaseNumber: 1.5 })).toEqual(['purchaseNumber']);
+    });
+});
+
+describe('promo de referido en el CRUD de promos', () => {
+    const CREATE = { name: 'Trae a un amigo', customerText: 'Gana $200', levers: {}, referral: REFERRAL };
+
+    it('CreateSalePromotionRequest acepta el bloque referral', () => {
+        expect(errorsOf(CreateSalePromotionRequest, CREATE)).toEqual([]);
+    });
+
+    it('CreateSalePromotionRequest valida el bloque referral anidado', () => {
+        expect(errorsOf(CreateSalePromotionRequest, { ...CREATE, referral: { ...REFERRAL, channel: 'APP' } })).toEqual([
+            'referral.channel',
+        ]);
+    });
+
+    it('UpdateSalePromotionRequest acepta el bloque referral', () => {
+        expect(errorsOf(UpdateSalePromotionRequest, { referral: REFERRAL })).toEqual([]);
+    });
+
+    it('ListSalePromotionsQuery filtra por kind y canal', () => {
+        expect(errorsOf(ListSalePromotionsQuery, { kind: 'REFERRAL', channel: 'CREDIT' })).toEqual([]);
+        expect(errorsOf(ListSalePromotionsQuery, { kind: 'X', channel: 'Y' })).toEqual(['kind', 'channel']);
+    });
+
+    it('SalePromotion trae la configuración de referido opcional', () => {
+        const referral: ReferralPromotionConfig = {
+            channel: ReferralPromotionChannelEnum.CREDIT,
+            trigger: ReferralTriggerEnum.FIRST_INSTALLMENT,
+            purchaseNumber: null,
+            installmentStreak: null,
+            minAmountCents: null,
+            windowDays: 60,
+            maxRewardsPerReferrer: null,
+            referrerReward: {
+                type: ReferralRewardTypeEnum.FIXED_BONUS,
+                amountCents: 100_00,
+                percentBps: null,
+                maxAmountCents: null,
+                coupon: null,
+            },
+            referredReward: null,
+        };
+        const promo: Pick<SalePromotion, 'promotionId' | 'referral'> = { promotionId: 'p-1', referral };
+        expect(promo.referral?.trigger).toBe('FIRST_INSTALLMENT');
+    });
+});

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

@@ -0,0 +1,73 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import { RetailPromotions } from '../../../src/index';
+import {
+    GetReferralRewardsByPhonesRequest,
+    ReferralRewardStatusEnum,
+    ReferralRewardTypeEnum,
+} from '../../../src/retailPromotions/index';
+import type { ReferralRewardsByPhonesResponse } from '../../../src/retailPromotions/index';
+import { ReferralRoleEnum } from '../../../src/retailCustomer/index';
+
+function errorsOf(payload: Record<string, unknown>): string[] {
+    const dto = plainToInstance(GetReferralRewardsByPhonesRequest, payload, { excludeExtraneousValues: true });
+    return validateSync(dto).map((e) => e.property);
+}
+
+const phonesOf = (n: number): string[] => Array.from({ length: n }, (_, i) => `55${String(i).padStart(8, '0')}`);
+
+describe('ReferralRewardStatusEnum', () => {
+    it('trae pagado, pendiente y no aplica', () => {
+        expect(Object.values(ReferralRewardStatusEnum)).toEqual(['PAID', 'PENDING', 'NOT_APPLICABLE']);
+    });
+});
+
+describe('GetReferralRewardsByPhonesRequest', () => {
+    it('acepta cadena y lote de teléfonos', () => {
+        expect(errorsOf({ retailerId: 'ret_1', phones: ['5512345678'] })).toEqual([]);
+    });
+
+    it('exige la cadena', () => {
+        expect(errorsOf({ phones: ['5512345678'] })).toEqual(['retailerId']);
+        expect(errorsOf({ retailerId: '', phones: ['5512345678'] })).toEqual(['retailerId']);
+    });
+
+    it('rechaza el lote vacío, de más de 100 o con teléfonos vacíos', () => {
+        expect(errorsOf({ retailerId: 'ret_1', phones: [] })).toEqual(['phones']);
+        expect(errorsOf({ retailerId: 'ret_1', phones: phonesOf(101) })).toEqual(['phones']);
+        expect(errorsOf({ retailerId: 'ret_1', phones: [''] })).toEqual(['phones']);
+        expect(errorsOf({ retailerId: 'ret_1', phones: phonesOf(100) })).toEqual([]);
+    });
+
+    it('sale por el index raíz', () => {
+        expect(new RetailPromotions.GetReferralRewardsByPhonesRequest()).toBeInstanceOf(
+            GetReferralRewardsByPhonesRequest,
+        );
+    });
+});
+
+describe('ReferralRewardsByPhonesResponse', () => {
+    it('agrupa los premios por teléfono con rol, tipo, monto, estado y fecha', () => {
+        const response: ReferralRewardsByPhonesResponse = {
+            phones: [
+                {
+                    phone: '5512345678',
+                    rewards: [
+                        {
+                            promotionId: 'promo_1',
+                            promotionName: 'Recomienda y gana',
+                            referralId: 'ref_1',
+                            role: ReferralRoleEnum.REFERRER,
+                            rewardType: ReferralRewardTypeEnum.FIXED_BONUS,
+                            amountCents: 20000,
+                            status: ReferralRewardStatusEnum.PAID,
+                            statusAt: '2026-10-12T10:00:00.000Z',
+                        },
+                    ],
+                },
+            ],
+        };
+        expect(response.phones[0].rewards[0].status).toBe('PAID');
+    });
+});

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

@@ -0,0 +1,26 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { CheckSalePromotionPaymentRequest } from '../../../src/retailPromotions/index';
+import type { PromotionPaymentNotEligibleDetails } from '../../../src/retailPromotions/index';
+
+const errorsOf = async (raw: Record<string, unknown>) =>
+  (await validate(plainToInstance(CheckSalePromotionPaymentRequest, raw) as object)).map((e) => e.property);
+
+describe('CheckSalePromotionPaymentRequest', () => {
+  it.each(['CASH', 'CARD', 'WIRE'])('acepta el medio %s', async (method) => {
+    expect(await errorsOf({ method })).toEqual([]);
+  });
+
+  it('rechaza un medio fuera del enum o ausente', async () => {
+    expect(await errorsOf({ method: 'BITCOIN' })).toEqual(['method']);
+    expect(await errorsOf({})).toEqual(['method']);
+  });
+
+  it('el detalle del 422 nombra la promo y los medios que acepta', () => {
+    const details: PromotionPaymentNotEligibleDetails = {
+      promotionIds: 'p-1,p-2', promotionId: 'p-1', promotionName: 'Bono', acceptedOptions: 'SUREKEEP,CASH',
+    };
+    expect(Object.keys(details)).toEqual(['promotionIds', 'promotionId', 'promotionName', 'acceptedOptions']);
+  });
+});

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

@@ -0,0 +1,34 @@
+import 'reflect-metadata';
+import {
+  RETAIL_PROMOTIONS_ERROR_HTTP_STATUS,
+  RetailPromotionsErrorCodeEnum,
+  SalePromotion,
+  SalePromotionSystemKeyEnum,
+  WelcomeBonusPromotionResponse,
+} from '../../../src/retailPromotions/index';
+import { WelcomeBonusAmountSourceEnum } from '../../../src/retailCustomer/index';
+
+describe('promo de sistema del bono de bienvenida', () => {
+  it('la llave de sistema solo tiene WELCOME_BONUS', () => {
+    expect(Object.values(SalePromotionSystemKeyEnum)).toEqual(['WELCOME_BONUS']);
+  });
+
+  it('la promo de venta expone systemKey opcional', () => {
+    const systemKey: SalePromotion['systemKey'] = SalePromotionSystemKeyEnum.WELCOME_BONUS;
+    expect(systemKey).toBe('WELCOME_BONUS');
+  });
+
+  it('la respuesta privada trae id, estado y monto', () => {
+    const response: WelcomeBonusPromotionResponse = { promotionId: 'p', active: true, amountCents: 2500 };
+    expect(Object.keys(response)).toEqual(['promotionId', 'active', 'amountCents']);
+  });
+
+  it('los candados de la promo de sistema son 422', () => {
+    expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS[RetailPromotionsErrorCodeEnum.SYSTEM_PROMOTION_TRANSITION_NOT_ALLOWED]).toBe(422);
+    expect(RETAIL_PROMOTIONS_ERROR_HTTP_STATUS[RetailPromotionsErrorCodeEnum.SYSTEM_PROMOTION_FIELD_LOCKED]).toBe(422);
+  });
+
+  it('el monto del bono puede salir de la promo de venta', () => {
+    expect(WelcomeBonusAmountSourceEnum.SALE_PROMOTION).toBe('SALE_PROMOTION');
+  });
+});

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

@@ -0,0 +1,78 @@
+import 'reflect-metadata';
+import { RetailWizard } from '../../../src/index';
+import type {
+    BackofficeCustomerReferral,
+    BackofficeCustomerReferralsResponse,
+    BackofficeReferralReward,
+} from '../../../src/retailWizard/index';
+import { ReferralRoleEnum, ReferralSourceEnum, ReferralStatusEnum } from '../../../src/retailCustomer/index';
+import { ReferralRewardStatusEnum, ReferralRewardTypeEnum } from '../../../src/retailPromotions/index';
+
+const reward: BackofficeReferralReward = {
+    promotionId: 'promo_1',
+    promotionName: 'Abre tu cuenta · ganan los dos',
+    role: ReferralRoleEnum.REFERRED,
+    rewardType: ReferralRewardTypeEnum.FIXED_BONUS,
+    amountCents: 10000,
+    status: ReferralRewardStatusEnum.PAID,
+    statusAt: '2025-03-14T10:00:00.000Z',
+};
+
+const referral: BackofficeCustomerReferral = {
+    referralId: 'ref_1',
+    name: 'Ana Sofía Martínez Ruiz',
+    phone: '5587654321',
+    email: null,
+    status: ReferralStatusEnum.SUREKEEP_CREDIT,
+    capture: {
+        source: ReferralSourceEnum.SALE,
+        storeId: 'store_1',
+        storeName: 'Tienda Coyoacán Centro',
+        saleId: 'sale_1',
+        saleFolio: 'F-10423',
+        accountOpeningSessionId: null,
+        capturedBy: 'user_1',
+        capturedAt: '2026-10-03T10:00:00.000Z',
+    },
+    updatedBy: 'user_1',
+    updatedAt: '2026-10-03T10:00:00.000Z',
+};
+
+describe('BackofficeCustomerReferralsResponse', () => {
+    it('lista los referidos con estado y captura, sin premios en la tanda A', () => {
+        const response: BackofficeCustomerReferralsResponse = { referrals: [referral], referredBy: null };
+        expect(response.referrals[0].rewards).toBeUndefined();
+        expect(response.referrals[0].capture.source).toBe('SALE');
+    });
+
+    it('suma premios por referido y el bloque «llegó recomendado por» en la tanda B', () => {
+        const response: BackofficeCustomerReferralsResponse = {
+            referrals: [{ ...referral, rewards: [{ ...reward, role: ReferralRoleEnum.REFERRER }] }],
+            referredBy: {
+                referralId: 'ref_9',
+                referrerCustomerId: 'rc_9',
+                referrerName: 'Mariana López Ortega',
+                referredAt: '2025-03-02T10:00:00.000Z',
+                rewards: [reward],
+            },
+        };
+        expect(response.referredBy?.rewards?.[0].promotionName).toBe('Abre tu cuenta · ganan los dos');
+    });
+
+    it('el bloque «llegó recomendado por» no exige promo', () => {
+        const response: BackofficeCustomerReferralsResponse = {
+            referrals: [],
+            referredBy: {
+                referralId: 'ref_9',
+                referrerCustomerId: 'rc_9',
+                referrerName: 'Mariana López Ortega',
+                referredAt: '2025-03-02T10:00:00.000Z',
+            },
+        };
+        expect(response.referredBy?.rewards).toBeUndefined();
+    });
+
+    it('el index raíz sigue exponiendo el módulo', () => {
+        expect(RetailWizard.WizardStepEnum).toBeDefined();
+    });
+});