@fiado/type-kit 3.565.0 → 3.567.0

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

@@ -61,6 +61,7 @@ describe('enums de referidos', () => {
 
 const SALE_BATCH = {
     source: 'SALE',
+    retailerId: 'r-1',
     storeId: 'st-1',
     wizardSessionId: 'ws-1',
     capturedBy: 'seller-1',
@@ -98,6 +99,13 @@ describe('CreateCustomerReferralsRequest', () => {
         expect(errorsOf(CreateCustomerReferralsRequest, { ...SALE_BATCH, capturedBy: ' ' })).toContain('capturedBy');
     });
 
+    it('exige la cadena de captura, también desde el cajón', () => {
+        const { retailerId: _retailerId, ...noRetailer } = SALE_BATCH;
+        expect(errorsOf(CreateCustomerReferralsRequest, noRetailer)).toEqual(['retailerId']);
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...noRetailer, source: 'BACKOFFICE' })).toEqual(['retailerId']);
+        expect(errorsOf(CreateCustomerReferralsRequest, { ...SALE_BATCH, retailerId: '  ' })).toEqual(['retailerId']);
+    });
+
     it('rechaza un origen fuera del catálogo', () => {
         expect(errorsOf(CreateCustomerReferralsRequest, { ...SALE_BATCH, source: 'WEB' })).toContain('source');
     });

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

@@ -0,0 +1,119 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import { RetailPromotions } from '../../../src/index';
+import {
+    EvaluateSalePromotionsRequest,
+    ListLiveReferralPromotionsQuery,
+    ReferralPromotionChannelEnum,
+    ReferralRewardTypeEnum,
+    ReferralTriggerEnum,
+} from '../../../src/retailPromotions/index';
+import type {
+    EvaluateSalePromotionsResponse,
+    ListLiveReferralPromotionsResponse,
+} from '../../../src/retailPromotions/index';
+
+type Dto = new () => object;
+
+const errorsOf = (dtoClass: Dto, raw: Record<string, unknown>): string[] =>
+    validateSync(plainToInstance(dtoClass, raw, { excludeExtraneousValues: true }) as object).map((e) => e.property);
+
+describe('EvaluateSalePromotionsRequest con teléfono', () => {
+    it('acepta el teléfono del cliente o su ausencia', () => {
+        expect(errorsOf(EvaluateSalePromotionsRequest, { sessionId: 's1', phone: '5512345678' })).toEqual([]);
+        expect(errorsOf(EvaluateSalePromotionsRequest, { sessionId: 's1' })).toEqual([]);
+    });
+
+    it('rechaza el teléfono vacío o no texto', () => {
+        expect(errorsOf(EvaluateSalePromotionsRequest, { sessionId: 's1', phone: '' })).toEqual(['phone']);
+        expect(errorsOf(EvaluateSalePromotionsRequest, { sessionId: 's1', phone: 5512345678 })).toEqual(['phone']);
+    });
+});
+
+describe('EvaluateSalePromotionsResponse con referredBy', () => {
+    it('trae solo el nombre de quien recomendó y lo que gana el recomendado', () => {
+        const response: EvaluateSalePromotionsResponse = {
+            promotions: [],
+            discountCode: null,
+            referredBy: {
+                name: 'María Fernanda',
+                rewards: [
+                    {
+                        promotionId: 'promo_1',
+                        promotionName: 'Gama alta · ganan los dos',
+                        reward: {
+                            type: ReferralRewardTypeEnum.SALE_DISCOUNT,
+                            amountCents: null,
+                            percentBps: 1000,
+                            maxAmountCents: null,
+                            coupon: null,
+                        },
+                    },
+                ],
+            },
+        };
+        expect(response.referredBy?.rewards?.[0].reward.percentBps).toBe(1000);
+    });
+
+    it('referredBy es opcional', () => {
+        const response: EvaluateSalePromotionsResponse = { promotions: [], discountCode: null };
+        expect(response.referredBy).toBeUndefined();
+    });
+});
+
+describe('ListLiveReferralPromotionsQuery', () => {
+    it('acepta sesión sola o con canal y evento', () => {
+        expect(errorsOf(ListLiveReferralPromotionsQuery, { sessionId: 's1' })).toEqual([]);
+        expect(
+            errorsOf(ListLiveReferralPromotionsQuery, {
+                sessionId: 's1',
+                channel: ReferralPromotionChannelEnum.CREDIT,
+                trigger: ReferralTriggerEnum.ACCOUNT_OPENED,
+            }),
+        ).toEqual([]);
+    });
+
+    it('exige la sesión', () => {
+        expect(errorsOf(ListLiveReferralPromotionsQuery, {})).toEqual(['sessionId']);
+        expect(errorsOf(ListLiveReferralPromotionsQuery, { sessionId: '' })).toEqual(['sessionId']);
+    });
+
+    it('rechaza canal o evento fuera del catálogo', () => {
+        expect(errorsOf(ListLiveReferralPromotionsQuery, { sessionId: 's1', channel: 'WALLET' })).toEqual(['channel']);
+        expect(errorsOf(ListLiveReferralPromotionsQuery, { sessionId: 's1', trigger: 'SIGNUP' })).toEqual(['trigger']);
+    });
+
+    it('sale por el index raíz', () => {
+        expect(new RetailPromotions.ListLiveReferralPromotionsQuery()).toBeInstanceOf(ListLiveReferralPromotionsQuery);
+    });
+});
+
+describe('ListLiveReferralPromotionsResponse', () => {
+    it('trae «tú ganas» y «tu amigo gana» por promo', () => {
+        const response: ListLiveReferralPromotionsResponse = {
+            items: [
+                {
+                    promotionId: 'promo_1',
+                    version: 2,
+                    name: 'Abre tu cuenta · ganan los dos',
+                    customerText: 'Cuando tu amigo abra su cuenta Fiado',
+                    channel: ReferralPromotionChannelEnum.SALE,
+                    trigger: ReferralTriggerEnum.ACCOUNT_OPENED,
+                    purchaseNumber: null,
+                    installmentStreak: null,
+                    validUntil: '2026-11-17T23:59:59.000Z',
+                    referrerReward: {
+                        type: ReferralRewardTypeEnum.FIXED_BONUS,
+                        amountCents: 15000,
+                        percentBps: null,
+                        maxAmountCents: null,
+                        coupon: null,
+                    },
+                    referredReward: null,
+                },
+            ],
+        };
+        expect(response.items[0].referrerReward.amountCents).toBe(15000);
+    });
+});

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

@@ -12,9 +12,12 @@ describe('CheckSalePromotionPaymentRequest', () => {
     expect(await errorsOf({ method })).toEqual([]);
   });
 
-  it('rechaza un medio fuera del enum o ausente', async () => {
+  it('rechaza un medio fuera del enum', async () => {
     expect(await errorsOf({ method: 'BITCOIN' })).toEqual(['method']);
-    expect(await errorsOf({})).toEqual(['method']);
+  });
+
+  it('sin medio es válido: se revisa contra la forma de pago de la sesión', async () => {
+    expect(await errorsOf({})).toEqual([]);
   });
 
   it('el detalle del 422 nombra la promo y los medios que acepta', () => {

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

@@ -45,6 +45,19 @@ describe('BackofficeCustomerReferralsResponse', () => {
         expect(response.referrals[0].capture.source).toBe('SALE');
     });
 
+    it('acepta el nombre visible de quien capturó, opcional y nullable', () => {
+        const named: BackofficeCustomerReferral = {
+            ...referral,
+            capture: { ...referral.capture, capturedByName: 'Laura Méndez (Admin SK)' },
+        };
+        const unresolved: BackofficeCustomerReferral = { ...referral, capture: { ...referral.capture, capturedByName: null } };
+        expect([named.capture.capturedByName, unresolved.capture.capturedByName, referral.capture.capturedByName]).toEqual([
+            'Laura Méndez (Admin SK)',
+            null,
+            undefined,
+        ]);
+    });
+
     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 }] }],

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

@@ -256,5 +256,15 @@ describe('respuestas de los M2M de Promociones', () => {
       undefined,
     ]);
     expect(asString).toBeDefined();
+
+    const referred: PrivateWizardSessionResponse = { ...base, customerPhone: '5512345678', customerPurchaseNumber: 2 };
+    // @ts-expect-error el número de compra es numérico
+    const purchaseAsString: PrivateWizardSessionResponse = { ...base, customerPurchaseNumber: '2' };
+    expect([referred.customerPhone, referred.customerPurchaseNumber, base.customerPurchaseNumber]).toEqual([
+      '5512345678',
+      2,
+      undefined,
+    ]);
+    expect(purchaseAsString).toBeDefined();
   });
 });

package/bin/retailCustomer/dtos/requests/CreateCustomerReferralsRequest.d.ts

@@ -8,6 +8,8 @@ export declare class CustomerReferralInput {
 /** Body de `privateCreateCustomerReferrals`: lote de referidos de un cliente. */
 export declare class CreateCustomerReferralsRequest {
     source: ReferralSourceEnum;
+    /** Cadena donde se captura el referido; «gana el primero» busca por cadena + teléfono. */
+    retailerId: string;
     /** Tienda de captura; obligatoria en venta y apertura. */
     storeId?: string;
     wizardSessionId?: string;

package/bin/retailCustomer/dtos/requests/CreateCustomerReferralsRequest.js

@@ -52,6 +52,13 @@ __decorate([
     (0, class_validator_1.IsEnum)(ReferralSourceEnum_1.ReferralSourceEnum),
     __metadata("design:type", String)
 ], CreateCustomerReferralsRequest.prototype, "source", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, Trim_1.Trim)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], CreateCustomerReferralsRequest.prototype, "retailerId", void 0);
 __decorate([
     (0, class_transformer_1.Expose)(),
     (0, class_validator_1.ValidateIf)((o) => o.source !== ReferralSourceEnum_1.ReferralSourceEnum.BACKOFFICE || o.storeId !== undefined),

package/bin/retailPromotions/dtos/requests/CheckSalePromotionPaymentRequest.d.ts

@@ -1,5 +1,6 @@
 import { SalePaymentMethodEnum } from '../../../retailWizard/enums/SalePaymentMethodEnum';
-/** Body de `POST /private/sessions/{sessionId}/sale-promotion/payment-check` (M2M): el medio con que se va a cobrar. */
+/** Body de `POST /private/sessions/{sessionId}/sale-promotion/payment-check` (M2M). */
 export declare class CheckSalePromotionPaymentRequest {
-    method: SalePaymentMethodEnum;
+    /** Medio del cobro de contado; ausente = se valida contra la forma de pago de la sesión (enganche o cierre a crédito). */
+    method?: SalePaymentMethodEnum;
 }

package/bin/retailPromotions/dtos/requests/CheckSalePromotionPaymentRequest.js

@@ -13,12 +13,13 @@ exports.CheckSalePromotionPaymentRequest = void 0;
 const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const SalePaymentMethodEnum_1 = require("../../../retailWizard/enums/SalePaymentMethodEnum");
-/** Body de `POST /private/sessions/{sessionId}/sale-promotion/payment-check` (M2M): el medio con que se va a cobrar. */
+/** Body de `POST /private/sessions/{sessionId}/sale-promotion/payment-check` (M2M). */
 class CheckSalePromotionPaymentRequest {
 }
 exports.CheckSalePromotionPaymentRequest = CheckSalePromotionPaymentRequest;
 __decorate([
     (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
     (0, class_validator_1.IsEnum)(SalePaymentMethodEnum_1.SalePaymentMethodEnum),
     __metadata("design:type", String)
 ], CheckSalePromotionPaymentRequest.prototype, "method", void 0);

package/bin/retailPromotions/dtos/requests/EvaluateSalePromotionsRequest.d.ts

@@ -2,4 +2,6 @@
 export declare class EvaluateSalePromotionsRequest {
     sessionId: string;
     discountCode?: string | null;
+    /** Teléfono del cliente de la venta; con él se sabe si llegó recomendado. */
+    phone?: string;
 }

package/bin/retailPromotions/dtos/requests/EvaluateSalePromotionsRequest.js

@@ -29,3 +29,10 @@ __decorate([
     (0, class_validator_1.IsNotEmpty)(),
     __metadata("design:type", String)
 ], EvaluateSalePromotionsRequest.prototype, "discountCode", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], EvaluateSalePromotionsRequest.prototype, "phone", void 0);

package/bin/retailPromotions/dtos/requests/ListLiveReferralPromotionsQuery.d.ts

@@ -0,0 +1,10 @@
+import { ReferralPromotionChannelEnum } from '../../enums/ReferralPromotionChannelEnum';
+import { ReferralTriggerEnum } from '../../enums/ReferralTriggerEnum';
+/** Query de las promos de referido vigentes del paso Referidos; la tienda sale de la sesión. */
+export declare class ListLiveReferralPromotionsQuery {
+    sessionId: string;
+    /** Sin canal: venta y crédito. */
+    channel?: ReferralPromotionChannelEnum;
+    /** `ACCOUNT_OPENED` en una apertura sin venta: solo las que se ganan al abrir cuenta. */
+    trigger?: ReferralTriggerEnum;
+}

package/bin/retailPromotions/dtos/requests/ListLiveReferralPromotionsQuery.js

@@ -0,0 +1,38 @@
+"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.ListLiveReferralPromotionsQuery = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const ReferralPromotionChannelEnum_1 = require("../../enums/ReferralPromotionChannelEnum");
+const ReferralTriggerEnum_1 = require("../../enums/ReferralTriggerEnum");
+/** Query de las promos de referido vigentes del paso Referidos; la tienda sale de la sesión. */
+class ListLiveReferralPromotionsQuery {
+}
+exports.ListLiveReferralPromotionsQuery = ListLiveReferralPromotionsQuery;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], ListLiveReferralPromotionsQuery.prototype, "sessionId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(ReferralPromotionChannelEnum_1.ReferralPromotionChannelEnum),
+    __metadata("design:type", String)
+], ListLiveReferralPromotionsQuery.prototype, "channel", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(ReferralTriggerEnum_1.ReferralTriggerEnum),
+    __metadata("design:type", String)
+], ListLiveReferralPromotionsQuery.prototype, "trigger", void 0);

package/bin/retailPromotions/dtos/responses/LiveReferralPromotionsResponse.d.ts

@@ -0,0 +1,24 @@
+import { ReferralPromotionChannelEnum } from '../../enums/ReferralPromotionChannelEnum';
+import { ReferralTriggerEnum } from '../../enums/ReferralTriggerEnum';
+import { ReferralReward } from '../ReferralPromotion';
+/** Promo de referido vigente para el paso Referidos: «tú ganas» y «tu amigo gana». */
+export interface LiveReferralPromotionItem {
+    promotionId: string;
+    version: number;
+    name: string;
+    customerText: string;
+    channel: ReferralPromotionChannelEnum;
+    trigger: ReferralTriggerEnum;
+    /** Solo en `NTH_PURCHASE`. */
+    purchaseNumber: number | null;
+    /** Solo en `INSTALLMENT_STREAK`. */
+    installmentStreak: number | null;
+    /** Fin de vigencia; `null` = sin fecha de fin. */
+    validUntil: string | null;
+    referrerReward: ReferralReward;
+    /** `null` = el recomendado no gana nada. */
+    referredReward: ReferralReward | null;
+}
+export interface ListLiveReferralPromotionsResponse {
+    items: LiveReferralPromotionItem[];
+}

package/bin/retailPromotions/dtos/responses/LiveReferralPromotionsResponse.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/retailPromotions/dtos/responses/WizardSalePromotionResponses.d.ts

@@ -9,6 +9,7 @@ import { SaleCouponAvailabilityEnum } from '../../enums/SaleCouponAvailabilityEn
 import { SalePromotionKindEnum } from '../../enums/SalePromotionKindEnum';
 import { SalePromotionLeverEnum } from '../../enums/SalePromotionLeverEnum';
 import { DiscountValue } from '../DiscountValue';
+import { ReferralReward } from '../ReferralPromotion';
 import { LinePromotionDiscount } from '../LinePromotionDiscount';
 import { SalePromotionLevers, SalePromotionScope } from '../SalePromotionLevers';
 /** Condiciones del cliente que pide la promo; solo vienen las que aplican. */
@@ -91,9 +92,21 @@ export interface EvaluatedDiscountCode {
     lines: LinePromotionDiscount[];
     totalDiscountCents: number;
 }
+/** Lo que gana el recomendado en una promo de referido vigente. */
+export interface EvaluatedReferredReward {
+    promotionId: string;
+    promotionName: string;
+    reward: ReferralReward;
+}
+/** Quién recomendó al cliente; solo viene si alguna promo vigente le da algo al recomendado. */
+export interface EvaluatedReferredBy {
+    name: string;
+    rewards?: EvaluatedReferredReward[];
+}
 export interface EvaluateSalePromotionsResponse {
     promotions: EvaluatedSalePromotion[];
     discountCode: EvaluatedDiscountCode | null;
+    referredBy?: EvaluatedReferredBy | null;
 }
 /** Promo de regalo del teléfono que quedó apartada. */
 export interface HeldGiftPromotion {

package/bin/retailPromotions/index.d.ts

@@ -63,6 +63,7 @@ export * from './dtos/requests/SkuSalePromotionsQuery';
 export * from './dtos/requests/ActiveSalePromotionsBySkusRequest';
 export * from './dtos/requests/CheckSalePromotionPaymentRequest';
 export * from './dtos/requests/GetReferralRewardsByPhonesRequest';
+export * from './dtos/requests/ListLiveReferralPromotionsQuery';
 export * from './dtos/responses/SalePromotionCrudResponses';
 export * from './dtos/responses/DiscountCodeResponses';
 export * from './dtos/responses/WizardSalePromotionResponses';
@@ -72,3 +73,4 @@ export * from './dtos/responses/ActiveSalePromotionsBySkusResponse';
 export * from './dtos/responses/WelcomeBonusPromotionResponse';
 export * from './dtos/responses/SalePromotionPaymentCheckResponses';
 export * from './dtos/responses/ReferralRewardsByPhonesResponses';
+export * from './dtos/responses/LiveReferralPromotionsResponse';

package/bin/retailPromotions/index.js

@@ -84,6 +84,7 @@ __exportStar(require("./dtos/requests/SkuSalePromotionsQuery"), exports);
 __exportStar(require("./dtos/requests/ActiveSalePromotionsBySkusRequest"), exports);
 __exportStar(require("./dtos/requests/CheckSalePromotionPaymentRequest"), exports);
 __exportStar(require("./dtos/requests/GetReferralRewardsByPhonesRequest"), exports);
+__exportStar(require("./dtos/requests/ListLiveReferralPromotionsQuery"), exports);
 // Response DTOs
 __exportStar(require("./dtos/responses/SalePromotionCrudResponses"), exports);
 __exportStar(require("./dtos/responses/DiscountCodeResponses"), exports);
@@ -94,3 +95,4 @@ __exportStar(require("./dtos/responses/ActiveSalePromotionsBySkusResponse"), exp
 __exportStar(require("./dtos/responses/WelcomeBonusPromotionResponse"), exports);
 __exportStar(require("./dtos/responses/SalePromotionPaymentCheckResponses"), exports);
 __exportStar(require("./dtos/responses/ReferralRewardsByPhonesResponses"), exports);
+__exportStar(require("./dtos/responses/LiveReferralPromotionsResponse"), exports);

package/bin/retailWizard/dtos/responses/BackofficeCustomerReferralsResponse.d.ts

@@ -26,6 +26,8 @@ export interface BackofficeReferralCapture {
     /** Solo en `OPENING`. */
     accountOpeningSessionId: string | null;
     capturedBy: string;
+    /** Nombre visible de quien capturó; `null` si no se resolvió. */
+    capturedByName?: string | null;
     capturedAt: string;
 }
 /** Referido del cliente en el cajón. */

package/bin/retailWizard/dtos/responses/PrivateWizardSessionResponse.d.ts

@@ -34,4 +34,8 @@ export interface PrivateWizardSessionResponse {
     payment?: WizardPayment | null;
     /** Valor efectivo del flag SPLIT_FINANCING_ENABLED del wizard. */
     splitFinancingEnabled?: boolean;
+    /** Teléfono del cliente de la sesión, 10 dígitos. */
+    customerPhone?: string;
+    /** Número de compra que sería esta venta en la cadena: 1 + ventas previas no canceladas. */
+    customerPurchaseNumber?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/type-kit",
-  "version": "3.565.0",
+  "version": "3.567.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

package/src/retailCustomer/dtos/requests/CreateCustomerReferralsRequest.ts

@@ -46,6 +46,13 @@ export class CreateCustomerReferralsRequest {
     @IsEnum(ReferralSourceEnum)
     source!: ReferralSourceEnum;
 
+    /** Cadena donde se captura el referido; «gana el primero» busca por cadena + teléfono. */
+    @Expose()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    retailerId!: string;
+
     /** Tienda de captura; obligatoria en venta y apertura. */
     @Expose()
     @ValidateIf((o: CreateCustomerReferralsRequest) => o.source !== ReferralSourceEnum.BACKOFFICE || o.storeId !== undefined)

package/src/retailPromotions/dtos/requests/CheckSalePromotionPaymentRequest.ts

@@ -1,10 +1,12 @@
 import { Expose } from 'class-transformer';
-import { IsEnum } from 'class-validator';
+import { IsEnum, IsOptional } from 'class-validator';
 import { SalePaymentMethodEnum } from '../../../retailWizard/enums/SalePaymentMethodEnum';
 
-/** Body de `POST /private/sessions/{sessionId}/sale-promotion/payment-check` (M2M): el medio con que se va a cobrar. */
+/** Body de `POST /private/sessions/{sessionId}/sale-promotion/payment-check` (M2M). */
 export class CheckSalePromotionPaymentRequest {
+    /** Medio del cobro de contado; ausente = se valida contra la forma de pago de la sesión (enganche o cierre a crédito). */
     @Expose()
+    @IsOptional()
     @IsEnum(SalePaymentMethodEnum)
-    method!: SalePaymentMethodEnum;
+    method?: SalePaymentMethodEnum;
 }

package/src/retailPromotions/dtos/requests/EvaluateSalePromotionsRequest.ts

@@ -13,4 +13,11 @@ export class EvaluateSalePromotionsRequest {
     @IsString()
     @IsNotEmpty()
     discountCode?: string | null;
+
+    /** Teléfono del cliente de la venta; con él se sabe si llegó recomendado. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @IsNotEmpty()
+    phone?: string;
 }

package/src/retailPromotions/dtos/requests/ListLiveReferralPromotionsQuery.ts

@@ -0,0 +1,24 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import { ReferralPromotionChannelEnum } from '../../enums/ReferralPromotionChannelEnum';
+import { ReferralTriggerEnum } from '../../enums/ReferralTriggerEnum';
+
+/** Query de las promos de referido vigentes del paso Referidos; la tienda sale de la sesión. */
+export class ListLiveReferralPromotionsQuery {
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    sessionId!: string;
+
+    /** Sin canal: venta y crédito. */
+    @Expose()
+    @IsOptional()
+    @IsEnum(ReferralPromotionChannelEnum)
+    channel?: ReferralPromotionChannelEnum;
+
+    /** `ACCOUNT_OPENED` en una apertura sin venta: solo las que se ganan al abrir cuenta. */
+    @Expose()
+    @IsOptional()
+    @IsEnum(ReferralTriggerEnum)
+    trigger?: ReferralTriggerEnum;
+}

package/src/retailPromotions/dtos/responses/LiveReferralPromotionsResponse.ts

@@ -0,0 +1,26 @@
+import { ReferralPromotionChannelEnum } from '../../enums/ReferralPromotionChannelEnum';
+import { ReferralTriggerEnum } from '../../enums/ReferralTriggerEnum';
+import { ReferralReward } from '../ReferralPromotion';
+
+/** Promo de referido vigente para el paso Referidos: «tú ganas» y «tu amigo gana». */
+export interface LiveReferralPromotionItem {
+    promotionId: string;
+    version: number;
+    name: string;
+    customerText: string;
+    channel: ReferralPromotionChannelEnum;
+    trigger: ReferralTriggerEnum;
+    /** Solo en `NTH_PURCHASE`. */
+    purchaseNumber: number | null;
+    /** Solo en `INSTALLMENT_STREAK`. */
+    installmentStreak: number | null;
+    /** Fin de vigencia; `null` = sin fecha de fin. */
+    validUntil: string | null;
+    referrerReward: ReferralReward;
+    /** `null` = el recomendado no gana nada. */
+    referredReward: ReferralReward | null;
+}
+
+export interface ListLiveReferralPromotionsResponse {
+    items: LiveReferralPromotionItem[];
+}

package/src/retailPromotions/dtos/responses/WizardSalePromotionResponses.ts

@@ -9,6 +9,7 @@ import { SaleCouponAvailabilityEnum } from '../../enums/SaleCouponAvailabilityEn
 import { SalePromotionKindEnum } from '../../enums/SalePromotionKindEnum';
 import { SalePromotionLeverEnum } from '../../enums/SalePromotionLeverEnum';
 import { DiscountValue } from '../DiscountValue';
+import { ReferralReward } from '../ReferralPromotion';
 import { LinePromotionDiscount } from '../LinePromotionDiscount';
 import { SalePromotionLevers, SalePromotionScope } from '../SalePromotionLevers';
 
@@ -99,9 +100,23 @@ export interface EvaluatedDiscountCode {
     totalDiscountCents: number;
 }
 
+/** Lo que gana el recomendado en una promo de referido vigente. */
+export interface EvaluatedReferredReward {
+    promotionId: string;
+    promotionName: string;
+    reward: ReferralReward;
+}
+
+/** Quién recomendó al cliente; solo viene si alguna promo vigente le da algo al recomendado. */
+export interface EvaluatedReferredBy {
+    name: string;
+    rewards?: EvaluatedReferredReward[];
+}
+
 export interface EvaluateSalePromotionsResponse {
     promotions: EvaluatedSalePromotion[];
     discountCode: EvaluatedDiscountCode | null;
+    referredBy?: EvaluatedReferredBy | null;
 }
 
 /** Promo de regalo del teléfono que quedó apartada. */

package/src/retailPromotions/index.ts

@@ -72,6 +72,7 @@ export * from './dtos/requests/SkuSalePromotionsQuery';
 export * from './dtos/requests/ActiveSalePromotionsBySkusRequest';
 export * from './dtos/requests/CheckSalePromotionPaymentRequest';
 export * from './dtos/requests/GetReferralRewardsByPhonesRequest';
+export * from './dtos/requests/ListLiveReferralPromotionsQuery';
 
 // Response DTOs
 export * from './dtos/responses/SalePromotionCrudResponses';
@@ -83,3 +84,4 @@ export * from './dtos/responses/ActiveSalePromotionsBySkusResponse';
 export * from './dtos/responses/WelcomeBonusPromotionResponse';
 export * from './dtos/responses/SalePromotionPaymentCheckResponses';
 export * from './dtos/responses/ReferralRewardsByPhonesResponses';
+export * from './dtos/responses/LiveReferralPromotionsResponse';

package/src/retailWizard/dtos/responses/BackofficeCustomerReferralsResponse.ts

@@ -28,6 +28,8 @@ export interface BackofficeReferralCapture {
     /** Solo en `OPENING`. */
     accountOpeningSessionId: string | null;
     capturedBy: string;
+    /** Nombre visible de quien capturó; `null` si no se resolvió. */
+    capturedByName?: string | null;
     capturedAt: string;
 }
 

package/src/retailWizard/dtos/responses/PrivateWizardSessionResponse.ts

@@ -35,4 +35,8 @@ export interface PrivateWizardSessionResponse {
   payment?: WizardPayment | null;
   /** Valor efectivo del flag SPLIT_FINANCING_ENABLED del wizard. */
   splitFinancingEnabled?: boolean;
+  /** Teléfono del cliente de la sesión, 10 dígitos. */
+  customerPhone?: string;
+  /** Número de compra que sería esta venta en la cadena: 1 + ventas previas no canceladas. */
+  customerPurchaseNumber?: number;
 }