@fiado/type-kit 3.489.0 → 3.490.0

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/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/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/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.490.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

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/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';