@fiado/type-kit 3.489.0 → 3.491.0

package/_test_/unit/loanCredit/customerPaymentDtos.test.ts

@@ -22,6 +22,7 @@ describe('loanCredit — opciones y resultado del pago del cliente', () => {
                 dueDate: '2026-10-01',
             },
             advance: { available: false, unavailableReason: LoanPaymentOptionUnavailableReasonEnum.NOT_AVAILABLE_YET },
+            prepayment: { available: false, unavailableReason: LoanPaymentOptionUnavailableReasonEnum.NOT_AVAILABLE_YET },
             settlement: {
                 available: true,
                 amountCents: 912345,
@@ -51,6 +52,7 @@ describe('loanCredit — opciones y resultado del pago del cliente', () => {
             pendingCharge: { kind: LoanAdHocChargeKindEnum.ADVANCE, amountCents: 105000 },
             nextInstallment: blocked,
             advance: blocked,
+            prepayment: blocked,
             settlement: blocked,
         };
 

package/_test_/unit/loanCredit/dtos/createCustomerPaymentRequest.test.ts

@@ -24,7 +24,7 @@ const VALID = {
 };
 
 describe.each([
-    ['LoanCustomerPaymentTypeEnum', LoanCustomerPaymentTypeEnum, ['NEXT_INSTALLMENT', 'SETTLEMENT']],
+    ['LoanCustomerPaymentTypeEnum', LoanCustomerPaymentTypeEnum, ['NEXT_INSTALLMENT', 'SETTLEMENT', 'ADVANCE', 'PREPAYMENT']],
     ['LoanNextInstallmentModeEnum', LoanNextInstallmentModeEnum, ['ADVANCE', 'COLLECT_DUE']],
     [
         'LoanPaymentOptionUnavailableReasonEnum',
@@ -44,7 +44,11 @@ describe.each([
 });
 
 describe('CreateCustomerPaymentRequest', () => {
-    it.each([[LoanCustomerPaymentTypeEnum.NEXT_INSTALLMENT], [LoanCustomerPaymentTypeEnum.SETTLEMENT]])(
+    it.each([
+        [LoanCustomerPaymentTypeEnum.NEXT_INSTALLMENT],
+        [LoanCustomerPaymentTypeEnum.SETTLEMENT],
+        [LoanCustomerPaymentTypeEnum.PREPAYMENT],
+    ])(
         'acepta el tipo %s',
         async type => {
             expect(await errorProperties({ ...VALID, type })).toEqual([]);
@@ -57,8 +61,18 @@ describe('CreateCustomerPaymentRequest', () => {
         );
     });
 
-    it.each([['ADVANCE'], ['PARTIAL']])('rechaza el tipo %s', async type => {
-        expect(await errorProperties({ ...VALID, type })).toEqual(['type']);
+    it('acepta varias cuotas con su número de cuotas', async () => {
+        expect(await errorProperties({ ...VALID, type: LoanCustomerPaymentTypeEnum.ADVANCE, installmentCount: 3 })).toEqual([]);
+    });
+
+    it.each([[1], [0], [2.5], ['3']])('rechaza el número de cuotas %p', async installmentCount => {
+        expect(await errorProperties({ ...VALID, type: LoanCustomerPaymentTypeEnum.ADVANCE, installmentCount })).toEqual([
+            'installmentCount',
+        ]);
+    });
+
+    it('rechaza un tipo desconocido', async () => {
+        expect(await errorProperties({ ...VALID, type: 'PARTIAL' })).toEqual(['type']);
     });
 
     it.each([[0], [-100], [10.5], ['912345']])('rechaza el monto %p', async expectedAmountCents => {

package/_test_/unit/loanOfferings/appliedPromotionBonus.test.ts

@@ -0,0 +1,22 @@
+import 'reflect-metadata';
+import { LoanOfferings } from '../../../src/index';
+import type { AppliedPromotionResponse } from '../../../src/loanOfferings/index';
+
+describe('AppliedPromotionResponse.pcfBonusCents', () => {
+    it('la ganadora del bono lo trae; las demás lo omiten', () => {
+        const winner: AppliedPromotionResponse = {
+            promotionId: 'p-1',
+            name: 'Bono',
+            version: 2,
+            appliedEffects: [LoanOfferings.PromotionEffectKindEnum.PCF_BONUS],
+            pcfBonusCents: 5_000,
+        };
+        const other: AppliedPromotionResponse = {
+            promotionId: 'p-0',
+            name: 'Tasa',
+            version: 1,
+            appliedEffects: [LoanOfferings.PromotionEffectKindEnum.TNA_OVERRIDE],
+        };
+        expect([winner.pcfBonusCents, other.pcfBonusCents]).toEqual([5_000, undefined]);
+    });
+});

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

@@ -0,0 +1,101 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import { RetailCustomer } from '../../../src/index';
+import { BonusTypeEnum, UpsertPromotionBonusRequest } from '../../../src/retailCustomer/index';
+import type { PromotionBonusEntryResponse } from '../../../src/retailCustomer/index';
+
+describe('BonusTypeEnum', () => {
+    it('distingue la bienvenida de las dos promociones', () => {
+        expect(Object.values(BonusTypeEnum)).toEqual(['WELCOME', 'CREDIT_PROMOTION', 'SALE_PROMOTION']);
+    });
+
+    it('sale por el index raíz', () => {
+        expect(RetailCustomer.BonusTypeEnum.SALE_PROMOTION).toBe('SALE_PROMOTION');
+    });
+});
+
+/** Valida como retail-customer-business: con `@Expose` y `excludeExtraneousValues`. */
+function errorsOf(payload: Record<string, unknown>): string[] {
+    const dto = plainToInstance(UpsertPromotionBonusRequest, payload, { excludeExtraneousValues: true });
+    return validateSync(dto).map((e) => e.property);
+}
+
+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',
+};
+
+describe('UpsertPromotionBonusRequest', () => {
+    it('acepta el PENDING «sin cuenta todavía», sin directorio', () => {
+        expect(errorsOf(PENDING_SALE)).toEqual([]);
+    });
+
+    it('ACCREDITED exige el directorio que recibió el depósito', () => {
+        expect(errorsOf({ ...PENDING_SALE, status: 'ACCREDITED' })).toContain('fiadoDirectoryId');
+        expect(errorsOf({ ...PENDING_SALE, status: 'ACCREDITED', fiadoDirectoryId: 'dir-1' })).toEqual([]);
+    });
+
+    it.each(['FAILED', 'UNVERIFIED'])('%s exige el motivo', (status) => {
+        expect(errorsOf({ ...PENDING_SALE, status })).toContain('failReason');
+        expect(errorsOf({ ...PENDING_SALE, status, failReason: 'VOID_EXPIRED' })).toEqual([]);
+    });
+
+    it('rechaza WELCOME: la bienvenida tiene su propio endpoint', () => {
+        expect(errorsOf({ ...PENDING_SALE, bonusType: 'WELCOME' })).toContain('bonusType');
+    });
+
+    it.each(['promotionId', 'sourceId', 'storeId', 'currency', 'idempotencyKey'])('rechaza %s vacío', (field) => {
+        expect(errorsOf({ ...PENDING_SALE, [field]: '  ' })).toContain(field);
+    });
+
+    it.each([0, -1, 1.5])('rechaza el monto %p', (amountCents) => {
+        expect(errorsOf({ ...PENDING_SALE, amountCents })).toContain('amountCents');
+    });
+
+    it('rechaza un estado fuera del libro', () => {
+        expect(errorsOf({ ...PENDING_SALE, status: 'SETTLED' })).toContain('status');
+    });
+
+    it('rechaza un motivo de más de 256 caracteres', () => {
+        expect(errorsOf({ ...PENDING_SALE, status: 'FAILED', failReason: 'x'.repeat(257) })).toContain('failReason');
+    });
+
+    it('sale por el index raíz', () => {
+        expect(new RetailCustomer.UpsertPromotionBonusRequest()).toBeInstanceOf(UpsertPromotionBonusRequest);
+    });
+});
+
+describe('PromotionBonusEntryResponse', () => {
+    it('describe el asiento de promo con su fuente', () => {
+        const entry: PromotionBonusEntryResponse = {
+            bonusId: 'B-1',
+            bonusType: BonusTypeEnum.CREDIT_PROMOTION,
+            promotionId: 'promo-1',
+            sourceId: 'credit-1',
+            retailCustomerId: 'rc-1',
+            fiadoDirectoryId: null,
+            saleId: null,
+            creditId: 'credit-1',
+            storeId: 'st-1',
+            amountCents: 5_000,
+            currency: 'MXN',
+            status: RetailCustomer.WelcomeBonusStatusEnum.PENDING,
+            failReason: null,
+            processorTransactionId: null,
+            idempotencyKey: 'credit-1',
+            fundedBy: 'VENTASLUGA',
+            settlementStatus: RetailCustomer.WelcomeBonusSettlementStatusEnum.PENDING,
+            resolvedAt: null,
+            createdAt: '2026-10-02T00:00:00.000Z',
+            updatedAt: '2026-10-02T00:00:00.000Z',
+        };
+        expect(entry.sourceId).toBe('credit-1');
+    });
+});

package/_test_/unit/retailLoan/paymentContract.test.ts

@@ -22,7 +22,7 @@ const errorProperties = async (body: object): Promise<string[]> => {
 };
 
 describe.each([
-    ['MyPaymentTypeEnum', MyPaymentTypeEnum, ['NEXT_INSTALLMENT', 'ADVANCE', 'SETTLEMENT']],
+    ['MyPaymentTypeEnum', MyPaymentTypeEnum, ['NEXT_INSTALLMENT', 'ADVANCE', 'SETTLEMENT', 'PREPAYMENT']],
     ['MyNextInstallmentModeEnum', MyNextInstallmentModeEnum, ['ADVANCE', 'COLLECT_DUE']],
     [
         'MyPaymentUnavailableReasonEnum',
@@ -85,6 +85,7 @@ describe('retailLoan — opciones y respuesta del pago', () => {
                 dueDate: '2026-10-01',
             },
             advance: { available: false, unavailableReason: MyPaymentUnavailableReasonEnum.NOT_AVAILABLE_YET },
+            prepayment: { available: false, unavailableReason: MyPaymentUnavailableReasonEnum.NOT_AVAILABLE_YET },
             settlement: {
                 available: true,
                 amount: 9123.45,
@@ -104,6 +105,7 @@ describe('retailLoan — opciones y respuesta del pago', () => {
             pendingPayment: { type: MyPaymentTypeEnum.NEXT_INSTALLMENT, amount: 1050 },
             nextInstallment: blocked,
             advance: blocked,
+            prepayment: blocked,
             settlement: blocked,
         };
 

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

@@ -0,0 +1,26 @@
+import 'reflect-metadata';
+import { LoanOfferings } from '../../../src/index';
+import type { QuoteResponse, WizardCreditPromotionBonus, WizardSession } from '../../../src/retailWizard/index';
+
+describe('bono de crédito en el contrato del wizard', () => {
+    it('la sesión lleva el desenlace persistido del bono de crédito', () => {
+        const bonus: WizardCreditPromotionBonus = {
+            promotionId: 'promo-1',
+            amountCents: 5_000,
+            status: LoanOfferings.PromotionBonusStatusEnum.RESERVED,
+        };
+        const session: Pick<WizardSession, 'creditPromotionBonus'> = { creditPromotionBonus: bonus };
+        expect(session.creditPromotionBonus?.status).toBe('RESERVED');
+    });
+
+    it('la sesión sin bono resuelto lo omite o lo manda null', () => {
+        const absent: Pick<WizardSession, 'creditPromotionBonus'> = {};
+        const nulled: Pick<WizardSession, 'creditPromotionBonus'> = { creditPromotionBonus: null };
+        expect([absent.creditPromotionBonus, nulled.creditPromotionBonus]).toEqual([undefined, null]);
+    });
+
+    it('la cotización puede traer el monto del bono que se cotizó', () => {
+        const quote: Pick<QuoteResponse, 'creditPromotionBonusCents'> = { creditPromotionBonusCents: 5_000 };
+        expect(quote.creditPromotionBonusCents).toBe(5_000);
+    });
+});

package/bin/loanCredit/dtos/requests/CreateCustomerPaymentRequest.d.ts

@@ -2,8 +2,10 @@ import { LoanCustomerPaymentTypeEnum } from '../../enums/LoanCustomerPaymentType
 /** Body de `POST /private/customers/:directoryId/credits/:creditId/payments` (loan-credit-business). */
 export declare class CreateCustomerPaymentRequest {
     type: LoanCustomerPaymentTypeEnum;
-    /** Monto que vio el cliente; si ya no coincide, responde 409 CUSTOMER_PAYMENT_AMOUNT_CHANGED. */
+    /** Monto que vio el cliente (en PREPAYMENT, el que eligió); si ya no coincide, responde 409 CUSTOMER_PAYMENT_AMOUNT_CHANGED. */
     expectedAmountCents: number;
     /** Llave del reintento: la misma llave con el mismo cuerpo devuelve la misma respuesta. */
     idempotencyKey: string;
+    /** Solo ADVANCE: cuántas cuotas adelanta. */
+    installmentCount?: number;
 }

package/bin/loanCredit/dtos/requests/CreateCustomerPaymentRequest.js

@@ -33,3 +33,10 @@ __decorate([
     (0, class_validator_1.IsUUID)(),
     __metadata("design:type", String)
 ], CreateCustomerPaymentRequest.prototype, "idempotencyKey", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(2),
+    __metadata("design:type", Number)
+], CreateCustomerPaymentRequest.prototype, "installmentCount", void 0);

package/bin/loanCredit/dtos/responses/LoanCustomerPaymentOptions.d.ts

@@ -8,6 +8,13 @@ export interface LoanCustomerPaymentOption {
     unavailableReason?: LoanPaymentOptionUnavailableReasonEnum;
     amountCents?: number;
 }
+/** Una cuota que se puede adelantar. */
+export interface LoanCustomerAdvanceInstallment {
+    installmentNumber: number;
+    /** `YYYY-MM-DD`. */
+    dueDate: string;
+    amountCents: number;
+}
 /** Response de `GET /private/customers/:directoryId/credits/:creditId/payment-options`. Montos en cents. */
 export interface LoanCustomerPaymentOptions {
     creditId: string;
@@ -15,6 +22,8 @@ export interface LoanCustomerPaymentOptions {
     pendingCharge?: {
         kind: LoanAdHocChargeKindEnum;
         amountCents: number;
+        /** Solo en un adelanto: las cuotas que cubre. */
+        installmentNumbers?: number[];
     };
     nextInstallment: LoanCustomerPaymentOption & {
         mode?: LoanNextInstallmentModeEnum;
@@ -22,8 +31,18 @@ export interface LoanCustomerPaymentOptions {
         /** `YYYY-MM-DD`. */
         dueDate?: string;
     };
-    /** Varias cuotas: hoy siempre `available: false` con `NOT_AVAILABLE_YET`. */
-    advance: LoanCustomerPaymentOption;
+    /** Varias cuotas. `installments` trae las `maxInstallments` que se pueden adelantar, en orden. */
+    advance: LoanCustomerPaymentOption & {
+        minInstallments?: number;
+        maxInstallments?: number;
+        installments?: LoanCustomerAdvanceInstallment[];
+    };
+    /** Abono a capital: monto libre entre `minAmountCents` y `maxAmountCents`. */
+    prepayment: LoanCustomerPaymentOption & {
+        minAmountCents?: number;
+        maxAmountCents?: number;
+        outstandingCapitalCents?: number;
+    };
     settlement: LoanCustomerPaymentOption & {
         /** La cotización de hoy; su `settlementAmountCents` es el `amountCents`. */
         quote?: LoanSettlementQuote;

package/bin/loanCredit/dtos/responses/LoanCustomerPaymentResult.d.ts

@@ -11,4 +11,6 @@ export interface LoanCustomerPaymentResult {
         status: CollectionResultStatus;
         amountCollectedCents: number;
     };
+    /** Solo ADVANCE: cuántas cuotas cubre. */
+    installmentCount?: number;
 }

package/bin/loanCredit/enums/LoanCustomerPaymentTypeEnum.d.ts

@@ -1,5 +1,9 @@
 /** Pago que el cliente puede pedir desde la app. */
 export declare enum LoanCustomerPaymentTypeEnum {
     NEXT_INSTALLMENT = "NEXT_INSTALLMENT",
-    SETTLEMENT = "SETTLEMENT"
+    SETTLEMENT = "SETTLEMENT",
+    /** Varias cuotas: las siguientes N tal como están, sin cambiar la tabla. */
+    ADVANCE = "ADVANCE",
+    /** Abono a capital: va completo a capital y baja las cuotas siguientes. */
+    PREPAYMENT = "PREPAYMENT"
 }

package/bin/loanCredit/enums/LoanCustomerPaymentTypeEnum.js

@@ -6,4 +6,8 @@ var LoanCustomerPaymentTypeEnum;
 (function (LoanCustomerPaymentTypeEnum) {
     LoanCustomerPaymentTypeEnum["NEXT_INSTALLMENT"] = "NEXT_INSTALLMENT";
     LoanCustomerPaymentTypeEnum["SETTLEMENT"] = "SETTLEMENT";
+    /** Varias cuotas: las siguientes N tal como están, sin cambiar la tabla. */
+    LoanCustomerPaymentTypeEnum["ADVANCE"] = "ADVANCE";
+    /** Abono a capital: va completo a capital y baja las cuotas siguientes. */
+    LoanCustomerPaymentTypeEnum["PREPAYMENT"] = "PREPAYMENT";
 })(LoanCustomerPaymentTypeEnum || (exports.LoanCustomerPaymentTypeEnum = LoanCustomerPaymentTypeEnum = {}));

package/bin/loanOfferings/dtos/responses/SimulationResultResponse.d.ts

@@ -27,6 +27,8 @@ export interface AppliedPromotionResponse {
     version: number;
     /** Palancas del plan que la promoción pisó. */
     appliedEffects: PromotionEffectKindEnum[];
+    /** Monto del bono PCF; solo en la promoción que gana el bono de la cotización. */
+    pcfBonusCents?: number;
 }
 /**
  * Una `CreditPlan` que el paso Base consideró para esta venta, haya ganado algún término o no.

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

@@ -0,0 +1,27 @@
+import { BonusTypeEnum } from '../../enums/BonusTypeEnum';
+import { WelcomeBonusStatusEnum } from '../../enums/WelcomeBonusStatusEnum';
+/**
+ * Asiento de un bono de promoción en el libro de bonos:
+ * `PUT /private/customers/:id/promotion-bonuses`. El libro es espejo del sistema de la promo.
+ */
+export declare class UpsertPromotionBonusRequest {
+    bonusType: BonusTypeEnum;
+    promotionId: string;
+    /** `creditId` en la promo de crédito, `saleId` en la de venta. */
+    sourceId: string;
+    /** Tienda de la venta: es la partición del asiento. */
+    storeId: string;
+    /** Obligatorio con `ACCREDITED`; el `PENDING` «sin cuenta todavía» no lo tiene. */
+    fiadoDirectoryId?: string;
+    amountCents: number;
+    currency: string;
+    status: WelcomeBonusStatusEnum;
+    idempotencyKey: string;
+    processorTransactionId?: string;
+    /** Resumen legible, sin el payload crudo del processor (el libro va sin PII). */
+    failReason?: string;
+    saleId?: string;
+    folio?: string;
+    wizardSessionId?: string;
+    sellerRetailUserId?: string;
+}

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

@@ -0,0 +1,139 @@
+"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.UpsertPromotionBonusRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const Trim_1 = require("../../../common/decorators/Trim");
+const BonusTypeEnum_1 = require("../../enums/BonusTypeEnum");
+const WelcomeBonusStatusEnum_1 = require("../../enums/WelcomeBonusStatusEnum");
+/** Tope del motivo libre que el caller escribe en el asiento. */
+const FREE_TEXT_MAX_LENGTH = 256;
+const PROMOTION_BONUS_TYPES = [BonusTypeEnum_1.BonusTypeEnum.CREDIT_PROMOTION, BonusTypeEnum_1.BonusTypeEnum.SALE_PROMOTION];
+const STATUSES_REQUIRING_REASON = [
+    WelcomeBonusStatusEnum_1.WelcomeBonusStatusEnum.FAILED,
+    WelcomeBonusStatusEnum_1.WelcomeBonusStatusEnum.UNVERIFIED,
+];
+/**
+ * Asiento de un bono de promoción en el libro de bonos:
+ * `PUT /private/customers/:id/promotion-bonuses`. El libro es espejo del sistema de la promo.
+ */
+class UpsertPromotionBonusRequest {
+}
+exports.UpsertPromotionBonusRequest = UpsertPromotionBonusRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsIn)(PROMOTION_BONUS_TYPES),
+    __metadata("design:type", String)
+], UpsertPromotionBonusRequest.prototype, "bonusType", 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)
+], UpsertPromotionBonusRequest.prototype, "promotionId", 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)
+], UpsertPromotionBonusRequest.prototype, "sourceId", 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)
+], UpsertPromotionBonusRequest.prototype, "storeId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)((o) => o.status === WelcomeBonusStatusEnum_1.WelcomeBonusStatusEnum.ACCREDITED || o.fiadoDirectoryId !== undefined),
+    (0, Trim_1.Trim)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)({ message: 'fiadoDirectoryId es obligatorio cuando status es ACCREDITED' }),
+    __metadata("design:type", String)
+], UpsertPromotionBonusRequest.prototype, "fiadoDirectoryId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsPositive)(),
+    __metadata("design:type", Number)
+], UpsertPromotionBonusRequest.prototype, "amountCents", 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)
+], UpsertPromotionBonusRequest.prototype, "currency", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsIn)(Object.values(WelcomeBonusStatusEnum_1.WelcomeBonusStatusEnum)),
+    __metadata("design:type", String)
+], UpsertPromotionBonusRequest.prototype, "status", 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)
+], UpsertPromotionBonusRequest.prototype, "idempotencyKey", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, Trim_1.Trim)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], UpsertPromotionBonusRequest.prototype, "processorTransactionId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.ValidateIf)((o) => STATUSES_REQUIRING_REASON.includes(o.status)),
+    (0, Trim_1.Trim)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)({ message: 'failReason es obligatorio cuando status es FAILED o UNVERIFIED' }),
+    (0, class_validator_1.MaxLength)(FREE_TEXT_MAX_LENGTH),
+    __metadata("design:type", String)
+], UpsertPromotionBonusRequest.prototype, "failReason", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, Trim_1.Trim)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], UpsertPromotionBonusRequest.prototype, "saleId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, Trim_1.Trim)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], UpsertPromotionBonusRequest.prototype, "folio", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, Trim_1.Trim)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], UpsertPromotionBonusRequest.prototype, "wizardSessionId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, Trim_1.Trim)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], UpsertPromotionBonusRequest.prototype, "sellerRetailUserId", void 0);

package/bin/retailCustomer/dtos/responses/PromotionBonusEntryResponse.d.ts

@@ -0,0 +1,27 @@
+import { BonusTypeEnum } from '../../enums/BonusTypeEnum';
+import { WelcomeBonusSettlementStatusEnum } from '../../enums/WelcomeBonusSettlementStatusEnum';
+import { WelcomeBonusStatusEnum } from '../../enums/WelcomeBonusStatusEnum';
+/** Asiento de un bono de promoción en el libro de bonos. Sin PII. */
+export interface PromotionBonusEntryResponse {
+    bonusId: string;
+    bonusType: BonusTypeEnum;
+    promotionId: string;
+    /** `creditId` en la promo de crédito, `saleId` en la de venta. */
+    sourceId: string;
+    retailCustomerId: string;
+    fiadoDirectoryId: string | null;
+    saleId: string | null;
+    creditId: string | null;
+    storeId: string;
+    amountCents: number | null;
+    currency: string;
+    status: WelcomeBonusStatusEnum;
+    failReason: string | null;
+    processorTransactionId: string | null;
+    idempotencyKey: string | null;
+    fundedBy: string;
+    settlementStatus: WelcomeBonusSettlementStatusEnum;
+    resolvedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}

package/bin/retailCustomer/dtos/responses/PromotionBonusEntryResponse.js

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

package/bin/retailCustomer/enums/BonusTypeEnum.d.ts

@@ -0,0 +1,6 @@
+/** Tipo de bono del libro de bonos. Un asiento sin tipo se lee como `WELCOME`. */
+export declare enum BonusTypeEnum {
+    WELCOME = "WELCOME",
+    CREDIT_PROMOTION = "CREDIT_PROMOTION",
+    SALE_PROMOTION = "SALE_PROMOTION"
+}

package/bin/retailCustomer/enums/BonusTypeEnum.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BonusTypeEnum = void 0;
+/** Tipo de bono del libro de bonos. Un asiento sin tipo se lee como `WELCOME`. */
+var BonusTypeEnum;
+(function (BonusTypeEnum) {
+    BonusTypeEnum["WELCOME"] = "WELCOME";
+    BonusTypeEnum["CREDIT_PROMOTION"] = "CREDIT_PROMOTION";
+    BonusTypeEnum["SALE_PROMOTION"] = "SALE_PROMOTION";
+})(BonusTypeEnum || (exports.BonusTypeEnum = BonusTypeEnum = {}));

package/bin/retailCustomer/index.d.ts

@@ -7,6 +7,7 @@ export * from './enums/RetailCustomerStatusEnum';
 export * from './enums/WelcomeBonusStatusEnum';
 export * from './enums/WelcomeBonusAmountSourceEnum';
 export * from './enums/WelcomeBonusSettlementStatusEnum';
+export * from './enums/BonusTypeEnum';
 export * from './dtos/KycReview';
 export * from './dtos/RetailAddress';
 export * from './dtos/RetailCustomer';
@@ -17,10 +18,12 @@ export * from './dtos/requests/AccountResultRequest';
 export * from './dtos/requests/KycReviewRequest';
 export * from './dtos/requests/WelcomeAccreditationRequest';
 export * from './dtos/requests/WelcomeAccreditationResultRequest';
+export * from './dtos/requests/UpsertPromotionBonusRequest';
 export * from './dtos/responses/CustomerResponse';
 export * from './dtos/responses/Customer360Response';
 export * from './dtos/responses/WelcomeBonusResponse';
 export * from './dtos/responses/WelcomeAccreditationResponse';
+export * from './dtos/responses/PromotionBonusEntryResponse';
 export * from './events/CustomerCreatedV1';
 export * from './events/CustomerUpdatedV1';
 export * from './events/CustomerKycVerifiedV1';

package/bin/retailCustomer/index.js

@@ -24,6 +24,7 @@ __exportStar(require("./enums/RetailCustomerStatusEnum"), exports);
 __exportStar(require("./enums/WelcomeBonusStatusEnum"), exports);
 __exportStar(require("./enums/WelcomeBonusAmountSourceEnum"), exports);
 __exportStar(require("./enums/WelcomeBonusSettlementStatusEnum"), exports);
+__exportStar(require("./enums/BonusTypeEnum"), exports);
 // Entidades (planas, con class-validator + @Expose)
 __exportStar(require("./dtos/KycReview"), exports);
 __exportStar(require("./dtos/RetailAddress"), exports);
@@ -36,11 +37,13 @@ __exportStar(require("./dtos/requests/AccountResultRequest"), exports);
 __exportStar(require("./dtos/requests/KycReviewRequest"), exports);
 __exportStar(require("./dtos/requests/WelcomeAccreditationRequest"), exports);
 __exportStar(require("./dtos/requests/WelcomeAccreditationResultRequest"), exports);
+__exportStar(require("./dtos/requests/UpsertPromotionBonusRequest"), exports);
 // Response DTOs
 __exportStar(require("./dtos/responses/CustomerResponse"), exports);
 __exportStar(require("./dtos/responses/Customer360Response"), exports);
 __exportStar(require("./dtos/responses/WelcomeBonusResponse"), exports);
 __exportStar(require("./dtos/responses/WelcomeAccreditationResponse"), exports);
+__exportStar(require("./dtos/responses/PromotionBonusEntryResponse"), exports);
 // Contratos de eventos (PascalCase + sufijo V1)
 __exportStar(require("./events/CustomerCreatedV1"), exports);
 __exportStar(require("./events/CustomerUpdatedV1"), exports);

package/bin/retailLoan/dtos/CreateMyPaymentRequest.d.ts

@@ -2,6 +2,8 @@ import { MyPaymentTypeEnum } from '../enums/MyPaymentTypeEnum';
 /** Body de `POST /benefits/{benefitId}/credits/{creditId}/payments`. La llave va en el header `Idempotency-Key`. */
 export declare class CreateMyPaymentRequest {
     type: MyPaymentTypeEnum;
-    /** Monto en pesos que vio el cliente; si ya no coincide, responde PAYMENT_AMOUNT_CHANGED. */
+    /** Monto en pesos que vio el cliente (en PREPAYMENT, el que eligió); si ya no coincide, responde PAYMENT_AMOUNT_CHANGED. */
     expectedAmount: number;
+    /** Solo ADVANCE: cuántas cuotas adelanta. */
+    installmentCount?: number;
 }

package/bin/retailLoan/dtos/CreateMyPaymentRequest.js

@@ -28,3 +28,10 @@ __decorate([
     (0, class_validator_1.IsPositive)(),
     __metadata("design:type", Number)
 ], CreateMyPaymentRequest.prototype, "expectedAmount", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(2),
+    __metadata("design:type", Number)
+], CreateMyPaymentRequest.prototype, "installmentCount", void 0);

package/bin/retailLoan/dtos/CreateMyPaymentResponse.d.ts

@@ -6,4 +6,6 @@ export interface CreateMyPaymentResponse {
     type: MyPaymentTypeEnum;
     amount: number;
     collection: MyCollectionOutcomeEnum;
+    /** Solo ADVANCE: cuántas cuotas cubre. */
+    installmentCount?: number;
 }

package/bin/retailLoan/dtos/MyPaymentOptions.d.ts

@@ -7,12 +7,21 @@ export interface MyPaymentOption {
     unavailableReason?: MyPaymentUnavailableReasonEnum;
     amount?: number;
 }
+/** Una cuota que se puede adelantar. `amount` en pesos. */
+export interface MyAdvanceInstallment {
+    installmentNumber: number;
+    /** `YYYY-MM-DD`. */
+    dueDate: string;
+    amount: number;
+}
 /** Opciones de pago de un crédito (`GET /benefits/{benefitId}/credits/{creditId}/payment-options`). Montos en pesos. */
 export interface MyPaymentOptions {
     /** Pago en curso; mientras exista, ninguna opción está disponible. */
     pendingPayment?: {
         type: MyPaymentTypeEnum;
         amount: number;
+        /** Solo en varias cuotas: las cuotas que cubre. */
+        installmentNumbers?: number[];
     };
     nextInstallment: MyPaymentOption & {
         mode?: MyNextInstallmentModeEnum;
@@ -20,7 +29,18 @@ export interface MyPaymentOptions {
         /** `YYYY-MM-DD`. */
         dueDate?: string;
     };
-    advance: MyPaymentOption;
+    /** Varias cuotas. `installments` trae las `maxInstallments` que se pueden adelantar, en orden. */
+    advance: MyPaymentOption & {
+        minInstallments?: number;
+        maxInstallments?: number;
+        installments?: MyAdvanceInstallment[];
+    };
+    /** Abono a capital: monto libre entre `minAmount` y `maxAmount`. */
+    prepayment: MyPaymentOption & {
+        minAmount?: number;
+        maxAmount?: number;
+        outstandingCapital?: number;
+    };
     settlement: MyPaymentOption & {
         breakdown?: {
             overdue: number;

package/bin/retailLoan/enums/MyPaymentTypeEnum.d.ts

@@ -1,6 +1,7 @@
-/** Pago que el cliente pide desde la app. `ADVANCE` = varias cuotas. */
+/** Pago que el cliente pide desde la app. `ADVANCE` = varias cuotas; `PREPAYMENT` = abono a capital. */
 export declare enum MyPaymentTypeEnum {
     NEXT_INSTALLMENT = "NEXT_INSTALLMENT",
     ADVANCE = "ADVANCE",
-    SETTLEMENT = "SETTLEMENT"
+    SETTLEMENT = "SETTLEMENT",
+    PREPAYMENT = "PREPAYMENT"
 }

package/bin/retailLoan/enums/MyPaymentTypeEnum.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MyPaymentTypeEnum = void 0;
-/** Pago que el cliente pide desde la app. `ADVANCE` = varias cuotas. */
+/** Pago que el cliente pide desde la app. `ADVANCE` = varias cuotas; `PREPAYMENT` = abono a capital. */
 var MyPaymentTypeEnum;
 (function (MyPaymentTypeEnum) {
     MyPaymentTypeEnum["NEXT_INSTALLMENT"] = "NEXT_INSTALLMENT";
     MyPaymentTypeEnum["ADVANCE"] = "ADVANCE";
     MyPaymentTypeEnum["SETTLEMENT"] = "SETTLEMENT";
+    MyPaymentTypeEnum["PREPAYMENT"] = "PREPAYMENT";
 })(MyPaymentTypeEnum || (exports.MyPaymentTypeEnum = MyPaymentTypeEnum = {}));

package/bin/retailWizard/dtos/WizardCreditPromotionBonus.d.ts

@@ -0,0 +1,8 @@
+import type { PromotionBonusStatusEnum } from '../../loanOfferings/enums/PromotionBonusStatusEnum';
+/** Desenlace del bono de la promo de crédito, persistido en la sesión del wizard. */
+export interface WizardCreditPromotionBonus {
+    promotionId: string;
+    amountCents: number;
+    /** `RESERVED` = en proceso; los otros tres son terminales. */
+    status: PromotionBonusStatusEnum;
+}

package/bin/retailWizard/dtos/WizardCreditPromotionBonus.js

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

package/bin/retailWizard/dtos/WizardSession.d.ts

@@ -13,6 +13,7 @@ import type { WizardProduct } from './WizardProduct';
 import type { WizardReservedLine } from './WizardReservedLine';
 import type { WizardResumeTarget } from './WizardResumeTarget';
 import type { WizardWelcome } from './WizardWelcome';
+import type { WizardCreditPromotionBonus } from './WizardCreditPromotionBonus';
 /** Modalidad de captura del KYC (M1 §213-329). */
 export type KycModality = 'CUSTOMER_LINK' | 'STORE_DEVICE' | 'MANUAL';
 /** Estado de la apertura de cuenta async (D35) — espejo de `RetailCustomer.accountStatus`. */
@@ -129,6 +130,8 @@ export interface WizardSession {
     folio: string | null;
     payment: WizardPayment | null;
     welcome: WizardWelcome | null;
+    /** Bono de la promo de crédito; ausente o `null` mientras no se haya reservado. */
+    creditPromotionBonus?: WizardCreditPromotionBonus | null;
     /** Contexto de crédito (pista SOFOM, pasos 04-09): PUNTEROS al dominio loan-*. Null en contado/externa. */
     loan: WizardLoan | null;
     saleId: string | null;

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

@@ -20,4 +20,6 @@ export interface QuotePlanBounds {
 export interface QuoteResponse {
     plan: QuotePlanBounds;
     credit: WizardCreditSummary;
+    /** Bono de la promo de crédito ganadora en esta cotización; ausente si no hay. */
+    creditPromotionBonusCents?: number;
 }

package/bin/retailWizard/index.d.ts

@@ -28,6 +28,7 @@ export * from './dtos/WizardConsents';
 export * from './dtos/WizardPayment';
 export * from './dtos/WizardProduct';
 export * from './dtos/WizardWelcome';
+export * from './dtos/WizardCreditPromotionBonus';
 export * from './dtos/SalePaymentDetail';
 export * from './dtos/ProspectNewCustomer';
 export * from './dtos/WizardBeneficiary';

package/bin/retailWizard/index.js

@@ -47,6 +47,7 @@ __exportStar(require("./dtos/WizardConsents"), exports);
 __exportStar(require("./dtos/WizardPayment"), exports);
 __exportStar(require("./dtos/WizardProduct"), exports);
 __exportStar(require("./dtos/WizardWelcome"), exports);
+__exportStar(require("./dtos/WizardCreditPromotionBonus"), exports);
 __exportStar(require("./dtos/SalePaymentDetail"), exports);
 __exportStar(require("./dtos/ProspectNewCustomer"), exports);
 __exportStar(require("./dtos/WizardBeneficiary"), exports);

package/package.json

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

package/src/loanCredit/dtos/requests/CreateCustomerPaymentRequest.ts

@@ -1,5 +1,5 @@
 import { Expose } from 'class-transformer';
-import { IsEnum, IsInt, IsUUID, Min } from 'class-validator';
+import { IsEnum, IsInt, IsOptional, IsUUID, Min } from 'class-validator';
 import { LoanCustomerPaymentTypeEnum } from '../../enums/LoanCustomerPaymentTypeEnum';
 
 /** Body de `POST /private/customers/:directoryId/credits/:creditId/payments` (loan-credit-business). */
@@ -8,7 +8,7 @@ export class CreateCustomerPaymentRequest {
     @IsEnum(LoanCustomerPaymentTypeEnum)
     type!: LoanCustomerPaymentTypeEnum;
 
-    /** Monto que vio el cliente; si ya no coincide, responde 409 CUSTOMER_PAYMENT_AMOUNT_CHANGED. */
+    /** Monto que vio el cliente (en PREPAYMENT, el que eligió); si ya no coincide, responde 409 CUSTOMER_PAYMENT_AMOUNT_CHANGED. */
     @Expose()
     @IsInt()
     @Min(1)
@@ -18,4 +18,11 @@ export class CreateCustomerPaymentRequest {
     @Expose()
     @IsUUID()
     idempotencyKey!: string;
+
+    /** Solo ADVANCE: cuántas cuotas adelanta. */
+    @Expose()
+    @IsOptional()
+    @IsInt()
+    @Min(2)
+    installmentCount?: number;
 }

package/src/loanCredit/dtos/responses/LoanCustomerPaymentOptions.ts

@@ -10,19 +10,42 @@ export interface LoanCustomerPaymentOption {
     amountCents?: number;
 }
 
+/** Una cuota que se puede adelantar. */
+export interface LoanCustomerAdvanceInstallment {
+    installmentNumber: number;
+    /** `YYYY-MM-DD`. */
+    dueDate: string;
+    amountCents: number;
+}
+
 /** Response de `GET /private/customers/:directoryId/credits/:creditId/payment-options`. Montos en cents. */
 export interface LoanCustomerPaymentOptions {
     creditId: string;
     /** Cargo ad hoc en curso; mientras exista, ninguna opción está disponible. */
-    pendingCharge?: { kind: LoanAdHocChargeKindEnum; amountCents: number };
+    pendingCharge?: {
+        kind: LoanAdHocChargeKindEnum;
+        amountCents: number;
+        /** Solo en un adelanto: las cuotas que cubre. */
+        installmentNumbers?: number[];
+    };
     nextInstallment: LoanCustomerPaymentOption & {
         mode?: LoanNextInstallmentModeEnum;
         installmentNumber?: number;
         /** `YYYY-MM-DD`. */
         dueDate?: string;
     };
-    /** Varias cuotas: hoy siempre `available: false` con `NOT_AVAILABLE_YET`. */
-    advance: LoanCustomerPaymentOption;
+    /** Varias cuotas. `installments` trae las `maxInstallments` que se pueden adelantar, en orden. */
+    advance: LoanCustomerPaymentOption & {
+        minInstallments?: number;
+        maxInstallments?: number;
+        installments?: LoanCustomerAdvanceInstallment[];
+    };
+    /** Abono a capital: monto libre entre `minAmountCents` y `maxAmountCents`. */
+    prepayment: LoanCustomerPaymentOption & {
+        minAmountCents?: number;
+        maxAmountCents?: number;
+        outstandingCapitalCents?: number;
+    };
     settlement: LoanCustomerPaymentOption & {
         /** La cotización de hoy; su `settlementAmountCents` es el `amountCents`. */
         quote?: LoanSettlementQuote;

package/src/loanCredit/dtos/responses/LoanCustomerPaymentResult.ts

@@ -9,4 +9,6 @@ export interface LoanCustomerPaymentResult {
     amountCents: number;
     /** Respuesta síncrona del motor; ausente si no contestó a tiempo. */
     collection?: { status: CollectionResultStatus; amountCollectedCents: number };
+    /** Solo ADVANCE: cuántas cuotas cubre. */
+    installmentCount?: number;
 }

package/src/loanCredit/enums/LoanCustomerPaymentTypeEnum.ts

@@ -2,4 +2,8 @@
 export enum LoanCustomerPaymentTypeEnum {
     NEXT_INSTALLMENT = 'NEXT_INSTALLMENT',
     SETTLEMENT = 'SETTLEMENT',
+    /** Varias cuotas: las siguientes N tal como están, sin cambiar la tabla. */
+    ADVANCE = 'ADVANCE',
+    /** Abono a capital: va completo a capital y baja las cuotas siguientes. */
+    PREPAYMENT = 'PREPAYMENT',
 }

package/src/loanOfferings/dtos/responses/SimulationResultResponse.ts

@@ -29,6 +29,8 @@ export interface AppliedPromotionResponse {
     version: number;
     /** Palancas del plan que la promoción pisó. */
     appliedEffects: PromotionEffectKindEnum[];
+    /** Monto del bono PCF; solo en la promoción que gana el bono de la cotización. */
+    pcfBonusCents?: number;
 }
 
 /**

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

@@ -0,0 +1,121 @@
+import { Expose } from 'class-transformer';
+import { IsIn, IsInt, IsNotEmpty, IsOptional, IsPositive, IsString, MaxLength, ValidateIf } from 'class-validator';
+import { Trim } from '../../../common/decorators/Trim';
+import { BonusTypeEnum } from '../../enums/BonusTypeEnum';
+import { WelcomeBonusStatusEnum } from '../../enums/WelcomeBonusStatusEnum';
+
+/** Tope del motivo libre que el caller escribe en el asiento. */
+const FREE_TEXT_MAX_LENGTH = 256;
+
+const PROMOTION_BONUS_TYPES = [BonusTypeEnum.CREDIT_PROMOTION, BonusTypeEnum.SALE_PROMOTION];
+
+const STATUSES_REQUIRING_REASON: WelcomeBonusStatusEnum[] = [
+    WelcomeBonusStatusEnum.FAILED,
+    WelcomeBonusStatusEnum.UNVERIFIED,
+];
+
+/**
+ * Asiento de un bono de promoción en el libro de bonos:
+ * `PUT /private/customers/:id/promotion-bonuses`. El libro es espejo del sistema de la promo.
+ */
+export class UpsertPromotionBonusRequest {
+    @Expose()
+    @IsIn(PROMOTION_BONUS_TYPES)
+    bonusType!: BonusTypeEnum;
+
+    @Expose()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    promotionId!: string;
+
+    /** `creditId` en la promo de crédito, `saleId` en la de venta. */
+    @Expose()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    sourceId!: string;
+
+    /** Tienda de la venta: es la partición del asiento. */
+    @Expose()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    storeId!: string;
+
+    /** Obligatorio con `ACCREDITED`; el `PENDING` «sin cuenta todavía» no lo tiene. */
+    @Expose()
+    @ValidateIf(
+        (o: UpsertPromotionBonusRequest) =>
+            o.status === WelcomeBonusStatusEnum.ACCREDITED || o.fiadoDirectoryId !== undefined,
+    )
+    @Trim()
+    @IsString()
+    @IsNotEmpty({ message: 'fiadoDirectoryId es obligatorio cuando status es ACCREDITED' })
+    fiadoDirectoryId?: string;
+
+    @Expose()
+    @IsInt()
+    @IsPositive()
+    amountCents!: number;
+
+    @Expose()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    currency!: string;
+
+    @Expose()
+    @IsIn(Object.values(WelcomeBonusStatusEnum))
+    status!: WelcomeBonusStatusEnum;
+
+    @Expose()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    idempotencyKey!: string;
+
+    @Expose()
+    @IsOptional()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    processorTransactionId?: string;
+
+    /** Resumen legible, sin el payload crudo del processor (el libro va sin PII). */
+    @Expose()
+    @ValidateIf((o: UpsertPromotionBonusRequest) => STATUSES_REQUIRING_REASON.includes(o.status))
+    @Trim()
+    @IsString()
+    @IsNotEmpty({ message: 'failReason es obligatorio cuando status es FAILED o UNVERIFIED' })
+    @MaxLength(FREE_TEXT_MAX_LENGTH)
+    failReason?: string;
+
+    @Expose()
+    @IsOptional()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    saleId?: string;
+
+    @Expose()
+    @IsOptional()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    folio?: string;
+
+    @Expose()
+    @IsOptional()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    wizardSessionId?: string;
+
+    @Expose()
+    @IsOptional()
+    @Trim()
+    @IsString()
+    @IsNotEmpty()
+    sellerRetailUserId?: string;
+}

package/src/retailCustomer/dtos/responses/PromotionBonusEntryResponse.ts

@@ -0,0 +1,28 @@
+import { BonusTypeEnum } from '../../enums/BonusTypeEnum';
+import { WelcomeBonusSettlementStatusEnum } from '../../enums/WelcomeBonusSettlementStatusEnum';
+import { WelcomeBonusStatusEnum } from '../../enums/WelcomeBonusStatusEnum';
+
+/** Asiento de un bono de promoción en el libro de bonos. Sin PII. */
+export interface PromotionBonusEntryResponse {
+    bonusId: string;
+    bonusType: BonusTypeEnum;
+    promotionId: string;
+    /** `creditId` en la promo de crédito, `saleId` en la de venta. */
+    sourceId: string;
+    retailCustomerId: string;
+    fiadoDirectoryId: string | null;
+    saleId: string | null;
+    creditId: string | null;
+    storeId: string;
+    amountCents: number | null;
+    currency: string;
+    status: WelcomeBonusStatusEnum;
+    failReason: string | null;
+    processorTransactionId: string | null;
+    idempotencyKey: string | null;
+    fundedBy: string;
+    settlementStatus: WelcomeBonusSettlementStatusEnum;
+    resolvedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+}

package/src/retailCustomer/enums/BonusTypeEnum.ts

@@ -0,0 +1,6 @@
+/** Tipo de bono del libro de bonos. Un asiento sin tipo se lee como `WELCOME`. */
+export enum BonusTypeEnum {
+    WELCOME = 'WELCOME',
+    CREDIT_PROMOTION = 'CREDIT_PROMOTION',
+    SALE_PROMOTION = 'SALE_PROMOTION',
+}

package/src/retailCustomer/index.ts

@@ -8,6 +8,7 @@ export * from './enums/RetailCustomerStatusEnum';
 export * from './enums/WelcomeBonusStatusEnum';
 export * from './enums/WelcomeBonusAmountSourceEnum';
 export * from './enums/WelcomeBonusSettlementStatusEnum';
+export * from './enums/BonusTypeEnum';
 
 // Entidades (planas, con class-validator + @Expose)
 export * from './dtos/KycReview';
@@ -22,12 +23,14 @@ export * from './dtos/requests/AccountResultRequest';
 export * from './dtos/requests/KycReviewRequest';
 export * from './dtos/requests/WelcomeAccreditationRequest';
 export * from './dtos/requests/WelcomeAccreditationResultRequest';
+export * from './dtos/requests/UpsertPromotionBonusRequest';
 
 // Response DTOs
 export * from './dtos/responses/CustomerResponse';
 export * from './dtos/responses/Customer360Response';
 export * from './dtos/responses/WelcomeBonusResponse';
 export * from './dtos/responses/WelcomeAccreditationResponse';
+export * from './dtos/responses/PromotionBonusEntryResponse';
 
 // Contratos de eventos (PascalCase + sufijo V1)
 export * from './events/CustomerCreatedV1';

package/src/retailLoan/dtos/CreateMyPaymentRequest.ts

@@ -1,5 +1,5 @@
 import { Expose } from 'class-transformer';
-import { IsEnum, IsNumber, IsPositive } from 'class-validator';
+import { IsEnum, IsInt, IsNumber, IsOptional, IsPositive, Min } from 'class-validator';
 import { MyPaymentTypeEnum } from '../enums/MyPaymentTypeEnum';
 
 /** Body de `POST /benefits/{benefitId}/credits/{creditId}/payments`. La llave va en el header `Idempotency-Key`. */
@@ -8,9 +8,16 @@ export class CreateMyPaymentRequest {
     @IsEnum(MyPaymentTypeEnum)
     type!: MyPaymentTypeEnum;
 
-    /** Monto en pesos que vio el cliente; si ya no coincide, responde PAYMENT_AMOUNT_CHANGED. */
+    /** Monto en pesos que vio el cliente (en PREPAYMENT, el que eligió); si ya no coincide, responde PAYMENT_AMOUNT_CHANGED. */
     @Expose()
     @IsNumber({ maxDecimalPlaces: 2 })
     @IsPositive()
     expectedAmount!: number;
+
+    /** Solo ADVANCE: cuántas cuotas adelanta. */
+    @Expose()
+    @IsOptional()
+    @IsInt()
+    @Min(2)
+    installmentCount?: number;
 }

package/src/retailLoan/dtos/CreateMyPaymentResponse.ts

@@ -7,4 +7,6 @@ export interface CreateMyPaymentResponse {
     type: MyPaymentTypeEnum;
     amount: number;
     collection: MyCollectionOutcomeEnum;
+    /** Solo ADVANCE: cuántas cuotas cubre. */
+    installmentCount?: number;
 }

package/src/retailLoan/dtos/MyPaymentOptions.ts

@@ -9,17 +9,41 @@ export interface MyPaymentOption {
     amount?: number;
 }
 
+/** Una cuota que se puede adelantar. `amount` en pesos. */
+export interface MyAdvanceInstallment {
+    installmentNumber: number;
+    /** `YYYY-MM-DD`. */
+    dueDate: string;
+    amount: number;
+}
+
 /** Opciones de pago de un crédito (`GET /benefits/{benefitId}/credits/{creditId}/payment-options`). Montos en pesos. */
 export interface MyPaymentOptions {
     /** Pago en curso; mientras exista, ninguna opción está disponible. */
-    pendingPayment?: { type: MyPaymentTypeEnum; amount: number };
+    pendingPayment?: {
+        type: MyPaymentTypeEnum;
+        amount: number;
+        /** Solo en varias cuotas: las cuotas que cubre. */
+        installmentNumbers?: number[];
+    };
     nextInstallment: MyPaymentOption & {
         mode?: MyNextInstallmentModeEnum;
         installmentNumber?: number;
         /** `YYYY-MM-DD`. */
         dueDate?: string;
     };
-    advance: MyPaymentOption;
+    /** Varias cuotas. `installments` trae las `maxInstallments` que se pueden adelantar, en orden. */
+    advance: MyPaymentOption & {
+        minInstallments?: number;
+        maxInstallments?: number;
+        installments?: MyAdvanceInstallment[];
+    };
+    /** Abono a capital: monto libre entre `minAmount` y `maxAmount`. */
+    prepayment: MyPaymentOption & {
+        minAmount?: number;
+        maxAmount?: number;
+        outstandingCapital?: number;
+    };
     settlement: MyPaymentOption & {
         breakdown?: { overdue: number; capital: number; interest: number; iva: number };
         savings?: number;

package/src/retailLoan/enums/MyPaymentTypeEnum.ts

@@ -1,6 +1,7 @@
-/** Pago que el cliente pide desde la app. `ADVANCE` = varias cuotas. */
+/** Pago que el cliente pide desde la app. `ADVANCE` = varias cuotas; `PREPAYMENT` = abono a capital. */
 export enum MyPaymentTypeEnum {
     NEXT_INSTALLMENT = 'NEXT_INSTALLMENT',
     ADVANCE = 'ADVANCE',
     SETTLEMENT = 'SETTLEMENT',
+    PREPAYMENT = 'PREPAYMENT',
 }

package/src/retailWizard/dtos/WizardCreditPromotionBonus.ts

@@ -0,0 +1,9 @@
+import type { PromotionBonusStatusEnum } from '../../loanOfferings/enums/PromotionBonusStatusEnum';
+
+/** Desenlace del bono de la promo de crédito, persistido en la sesión del wizard. */
+export interface WizardCreditPromotionBonus {
+    promotionId: string;
+    amountCents: number;
+    /** `RESERVED` = en proceso; los otros tres son terminales. */
+    status: PromotionBonusStatusEnum;
+}

package/src/retailWizard/dtos/WizardSession.ts

@@ -13,6 +13,7 @@ import type { WizardProduct } from './WizardProduct';
 import type { WizardReservedLine } from './WizardReservedLine';
 import type { WizardResumeTarget } from './WizardResumeTarget';
 import type { WizardWelcome } from './WizardWelcome';
+import type { WizardCreditPromotionBonus } from './WizardCreditPromotionBonus';
 
 /** Modalidad de captura del KYC (M1 §213-329). */
 export type KycModality = 'CUSTOMER_LINK' | 'STORE_DEVICE' | 'MANUAL';
@@ -133,6 +134,8 @@ export interface WizardSession {
   folio: string | null;
   payment: WizardPayment | null;
   welcome: WizardWelcome | null;
+  /** Bono de la promo de crédito; ausente o `null` mientras no se haya reservado. */
+  creditPromotionBonus?: WizardCreditPromotionBonus | null;
   /** Contexto de crédito (pista SOFOM, pasos 04-09): PUNTEROS al dominio loan-*. Null en contado/externa. */
   loan: WizardLoan | null;
   saleId: string | null;

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

@@ -22,4 +22,6 @@ export interface QuotePlanBounds {
 export interface QuoteResponse {
     plan: QuotePlanBounds;
     credit: WizardCreditSummary;
+    /** Bono de la promo de crédito ganadora en esta cotización; ausente si no hay. */
+    creditPromotionBonusCents?: number;
 }

package/src/retailWizard/index.ts

@@ -33,6 +33,7 @@ export * from './dtos/WizardConsents';
 export * from './dtos/WizardPayment';
 export * from './dtos/WizardProduct';
 export * from './dtos/WizardWelcome';
+export * from './dtos/WizardCreditPromotionBonus';
 export * from './dtos/SalePaymentDetail';
 export * from './dtos/ProspectNewCustomer';
 export * from './dtos/WizardBeneficiary';