@fiado/type-kit 3.363.0 → 3.365.0

package/bin/loanOfferings/enums/PromotionLogEventEnum.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromotionLogEventEnum = void 0;
+/**
+ * Evento de la bitácora de promociones (`<T>LoanPromotionLog_GT`), que alimenta el tab «Auditoría».
+ * @enum {string}
+ */
+var PromotionLogEventEnum;
+(function (PromotionLogEventEnum) {
+    PromotionLogEventEnum["CREATE"] = "CREATE";
+    PromotionLogEventEnum["PUBLISH"] = "PUBLISH";
+    PromotionLogEventEnum["PAUSE"] = "PAUSE";
+    PromotionLogEventEnum["RESUME"] = "RESUME";
+    PromotionLogEventEnum["EXPIRE"] = "EXPIRE";
+    PromotionLogEventEnum["UPDATE"] = "UPDATE";
+})(PromotionLogEventEnum || (exports.PromotionLogEventEnum = PromotionLogEventEnum = {}));

package/bin/loanOfferings/enums/PromotionPhaseEnum.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Fase de vigencia de una promoción PUBLICADA, derivada de `validFrom`/`validUntil` contra hoy.
+ * No se persiste — así no hace falta un cron que mueva estados a medianoche. `null` cuando el
+ * estado persistido no es `PUBLISHED`.
+ * @enum {string}
+ */
+export declare enum PromotionPhaseEnum {
+    SCHEDULED = "SCHEDULED",
+    ACTIVE = "ACTIVE",
+    EXPIRED = "EXPIRED"
+}

package/bin/loanOfferings/enums/PromotionPhaseEnum.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromotionPhaseEnum = void 0;
+/**
+ * Fase de vigencia de una promoción PUBLICADA, derivada de `validFrom`/`validUntil` contra hoy.
+ * No se persiste — así no hace falta un cron que mueva estados a medianoche. `null` cuando el
+ * estado persistido no es `PUBLISHED`.
+ * @enum {string}
+ */
+var PromotionPhaseEnum;
+(function (PromotionPhaseEnum) {
+    PromotionPhaseEnum["SCHEDULED"] = "SCHEDULED";
+    PromotionPhaseEnum["ACTIVE"] = "ACTIVE";
+    PromotionPhaseEnum["EXPIRED"] = "EXPIRED";
+})(PromotionPhaseEnum || (exports.PromotionPhaseEnum = PromotionPhaseEnum = {}));

package/bin/loanOfferings/enums/PromotionStatusEnum.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Estado PERSISTIDO de una promoción del motor (portal-admin-sk-promociones).
+ * `EXPIRED` es terminal. La «fase» que ve el operador (programada / activa / vencida) NO se guarda:
+ * se deriva de las fechas — ver `PromotionPhaseEnum`.
+ * @enum {string}
+ */
+export declare enum PromotionStatusEnum {
+    DRAFT = "DRAFT",
+    PUBLISHED = "PUBLISHED",
+    PAUSED = "PAUSED",
+    EXPIRED = "EXPIRED"
+}

package/bin/loanOfferings/enums/PromotionStatusEnum.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromotionStatusEnum = void 0;
+/**
+ * Estado PERSISTIDO de una promoción del motor (portal-admin-sk-promociones).
+ * `EXPIRED` es terminal. La «fase» que ve el operador (programada / activa / vencida) NO se guarda:
+ * se deriva de las fechas — ver `PromotionPhaseEnum`.
+ * @enum {string}
+ */
+var PromotionStatusEnum;
+(function (PromotionStatusEnum) {
+    PromotionStatusEnum["DRAFT"] = "DRAFT";
+    PromotionStatusEnum["PUBLISHED"] = "PUBLISHED";
+    PromotionStatusEnum["PAUSED"] = "PAUSED";
+    PromotionStatusEnum["EXPIRED"] = "EXPIRED";
+})(PromotionStatusEnum || (exports.PromotionStatusEnum = PromotionStatusEnum = {}));

package/bin/loanOfferings/index.d.ts

@@ -4,9 +4,14 @@ export * from './enums/ProductTierEnum';
 export * from './enums/CreditPlanStatusEnum';
 export * from './enums/FinancierTypeEnum';
 export * from './enums/FinancierStatusEnum';
+export * from './enums/PromotionStatusEnum';
+export * from './enums/PromotionEffectKindEnum';
+export * from './enums/PromotionPhaseEnum';
+export * from './enums/PromotionLogEventEnum';
 export * from './dtos/CreditPlan';
 export * from './dtos/Financier';
 export * from './dtos/RetailerCreditPlan';
+export * from './dtos/PromotionEffect';
 export * from './dtos/requests/CreateCreditPlanRequest';
 export * from './dtos/requests/UpdateCreditPlanRequest';
 export * from './dtos/requests/ChangeCreditPlanStatusRequest';
@@ -15,7 +20,13 @@ export * from './dtos/requests/CreateFinancierRequest';
 export * from './dtos/requests/UpdateFinancierRequest';
 export * from './dtos/requests/ChangeFinancierStatusRequest';
 export * from './dtos/requests/ReorderFinancierRequest';
+export * from './dtos/requests/PromotionEffectInput';
+export * from './dtos/requests/CreatePromotionRequest';
+export * from './dtos/requests/UpdatePromotionRequest';
+export * from './dtos/requests/ChangePromotionStatusRequest';
 export * from './dtos/responses/CreditPlanResponse';
 export * from './dtos/responses/FinancierResponse';
 export * from './dtos/responses/RetailerCreditPlanResponse';
 export * from './dtos/responses/SimulationResultResponse';
+export * from './dtos/responses/PromotionResponse';
+export * from './dtos/responses/PromotionLogEntryResponse';

package/bin/loanOfferings/index.js

@@ -21,10 +21,15 @@ __exportStar(require("./enums/ProductTierEnum"), exports);
 __exportStar(require("./enums/CreditPlanStatusEnum"), exports);
 __exportStar(require("./enums/FinancierTypeEnum"), exports);
 __exportStar(require("./enums/FinancierStatusEnum"), exports);
+__exportStar(require("./enums/PromotionStatusEnum"), exports);
+__exportStar(require("./enums/PromotionEffectKindEnum"), exports);
+__exportStar(require("./enums/PromotionPhaseEnum"), exports);
+__exportStar(require("./enums/PromotionLogEventEnum"), exports);
 // Entity DTOs
 __exportStar(require("./dtos/CreditPlan"), exports);
 __exportStar(require("./dtos/Financier"), exports);
 __exportStar(require("./dtos/RetailerCreditPlan"), exports);
+__exportStar(require("./dtos/PromotionEffect"), exports);
 // Request DTOs
 __exportStar(require("./dtos/requests/CreateCreditPlanRequest"), exports);
 __exportStar(require("./dtos/requests/UpdateCreditPlanRequest"), exports);
@@ -34,8 +39,14 @@ __exportStar(require("./dtos/requests/CreateFinancierRequest"), exports);
 __exportStar(require("./dtos/requests/UpdateFinancierRequest"), exports);
 __exportStar(require("./dtos/requests/ChangeFinancierStatusRequest"), exports);
 __exportStar(require("./dtos/requests/ReorderFinancierRequest"), exports);
+__exportStar(require("./dtos/requests/PromotionEffectInput"), exports);
+__exportStar(require("./dtos/requests/CreatePromotionRequest"), exports);
+__exportStar(require("./dtos/requests/UpdatePromotionRequest"), exports);
+__exportStar(require("./dtos/requests/ChangePromotionStatusRequest"), exports);
 // Response DTOs
 __exportStar(require("./dtos/responses/CreditPlanResponse"), exports);
 __exportStar(require("./dtos/responses/FinancierResponse"), exports);
 __exportStar(require("./dtos/responses/RetailerCreditPlanResponse"), exports);
 __exportStar(require("./dtos/responses/SimulationResultResponse"), exports);
+__exportStar(require("./dtos/responses/PromotionResponse"), exports);
+__exportStar(require("./dtos/responses/PromotionLogEntryResponse"), exports);

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

@@ -1,9 +1,26 @@
+import { Status } from '../../../card/enums/Status';
+import { VirtualOrPhysical } from '../../../card/enums/VirtualOrPhysical';
 import { CustomerResponse } from './CustomerResponse';
 /** Resumen de wallet (nivel N1/N2 + saldo) para el Cliente 360. */
 export interface Customer360Wallet {
     accountLevel: 1 | 2 | null;
     clabe: string | null;
-    balanceCents: number;
+    /**
+     * Saldo en centavos, o `null` cuando la fuente no lo trajo. Era `number` a secas y eso obligaba
+     * a mandar `0` por un bloque ilegible, indistinguible de un saldo cero real.
+     */
+    balanceCents: number | null;
+}
+/**
+ * Tarjeta del cliente para el Cliente 360. Los campos espejan lo que devuelve `CardResponse` de
+ * `fiado-card-business`; `issued` en `false` deja los demás en `null` (no hay tarjeta que describir).
+ */
+export interface Customer360Card {
+    issued: boolean;
+    /** Últimos dígitos del PAN, tal como los nombra `CardResponse.panLastDigit`. */
+    panLastDigit: string | null;
+    status: Status | null;
+    virtualOrPhysical: VirtualOrPhysical | null;
 }
 /** Ítem de compra en el historial del Cliente 360 (del GSI customerId-soldAt). */
 export interface Customer360Purchase {
@@ -28,6 +45,8 @@ export interface Customer360Prospect {
 export interface Customer360Response {
     customer: CustomerResponse;
     wallet: Customer360Wallet;
+    /** Tarjeta del cliente. Opcional: los consumidores que no la piden siguen compilando igual. */
+    card?: Customer360Card;
     purchases: Customer360Purchase[];
     prospects: Customer360Prospect[];
 }

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

@@ -1,3 +1,4 @@
+import { KycReview } from '../KycReview';
 import { RetailAddress } from '../RetailAddress';
 import { AccountStatusEnum } from '../../enums/AccountStatusEnum';
 import { KycModalityEnum } from '../../enums/KycModalityEnum';
@@ -44,6 +45,11 @@ export interface CustomerResponse {
     kycStatus: RetailKycStatusEnum;
     kycModality: KycModalityEnum | null;
     kycScore: number | null;
+    /**
+     * Veredicto manual del oficial de Cumplimiento (D21), ya persistido en el cliente. Ausente
+     * mientras nadie resolvió el KYC a mano — opcional para no romper a los consumidores actuales.
+     */
+    kycReview?: KycReview;
     metamapVerificationId: string | null;
     pldFlag: boolean;
     notes: string | null;

package/package.json

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

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

@@ -81,4 +81,20 @@ export class OriginateLoanCreditRequest {
     @IsOptional()
     @IsString()
     imei?: string;
+
+    /**
+     * Tienda donde se vende. El motor la persiste y la reenvía al simulador del catálogo en cada
+     * cotización — al RE-cotizar el wizard no la vuelve a mandar, así que sin guardarla la venta
+     * perdería su promoción a mitad del paso 06.
+     */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    storeId?: string;
+
+    /** SKU del equipo, por el mismo motivo que `storeId`: resuelve promociones acotadas por producto. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    productSku?: string;
 }

package/src/loanOfferings/dtos/PromotionEffect.ts

@@ -0,0 +1,15 @@
+/**
+ * Palanca que la promoción aplica sobre el plan de crédito. Al menos una clave debe venir presente
+ * (el lambda rechaza el efecto vacío con 422). Montos en **cents**; porcentajes y TNA en decimal,
+ * igual que `CreditPlan`.
+ */
+export interface PromotionEffect {
+    /** Delta NEGATIVO sobre el enganche mínimo del plan (`-0.20` = veinte puntos menos). */
+    downPaymentDeltaPct: number | null;
+    /** Bono que se abona a la tarjeta PCF al activar el crédito. */
+    pcfBonusCents: number | null;
+    /** TNA que reemplaza a la del plan, siempre hacia abajo (`1.80` = 180% en vez de 200%). */
+    tnaOverride: number | null;
+    /** Techo de monto financiable que reemplaza al del plan. */
+    maxAmountOverrideCents: number | null;
+}

package/src/loanOfferings/dtos/requests/ChangePromotionStatusRequest.ts

@@ -0,0 +1,19 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsOptional, IsString } from 'class-validator';
+import { PromotionStatusEnum } from '../../enums/PromotionStatusEnum';
+
+/**
+ * Body de PUT /promotions/:promotionId/status — publicar, pausar, reanudar o vencer.
+ * Transiciones válidas: `DRAFT→PUBLISHED`, `PUBLISHED⇄PAUSED`, `PUBLISHED|PAUSED→EXPIRED`.
+ * `reason` acompaña la pausa y queda en la bitácora.
+ */
+export class ChangePromotionStatusRequest {
+    @Expose()
+    @IsEnum(PromotionStatusEnum)
+    status!: PromotionStatusEnum;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    reason?: string | null;
+}

package/src/loanOfferings/dtos/requests/CreatePromotionRequest.ts

@@ -0,0 +1,77 @@
+import { Expose, Type } from 'class-transformer';
+import {
+    ArrayNotEmpty,
+    IsArray,
+    IsEnum,
+    IsInt,
+    IsISO8601,
+    IsOptional,
+    IsString,
+    ValidateNested,
+} from 'class-validator';
+import { CreditPlanLevelEnum } from '../../enums/CreditPlanLevelEnum';
+import { PromotionEffectInput } from './PromotionEffectInput';
+
+/**
+ * Body de POST /promotions — alta de una promoción del motor.
+ * Nace en `DRAFT`: el estado, `promotionId`, `version`, los contadores de consumo y la auditoría
+ * los asigna el lambda y NO viajan en el request. `budgetMaxCents` ausente/`null` = sin tope.
+ */
+export class CreatePromotionRequest {
+    @Expose()
+    @IsString()
+    name!: string;
+
+    @Expose()
+    @IsString()
+    description!: string;
+
+    @Expose()
+    @ValidateNested()
+    @Type(() => PromotionEffectInput)
+    effect!: PromotionEffectInput;
+
+    /** Segmento de clientes al que apunta la promoción. */
+    @Expose()
+    @IsString()
+    segmentId!: string;
+
+    @Expose()
+    @IsArray()
+    @ArrayNotEmpty()
+    @IsEnum(CreditPlanLevelEnum, { each: true })
+    targetLevels!: CreditPlanLevelEnum[];
+
+    /** SKUs alcanzados; ausente o `null` = todos los productos. */
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @IsString({ each: true })
+    productSkus?: string[] | null;
+
+    /** Tiendas alcanzadas. `null` o ausente = todas. */
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @IsString({ each: true })
+    storeIds?: string[] | null;
+
+    @Expose()
+    @IsOptional()
+    @IsISO8601()
+    validFrom?: string | null;
+
+    @Expose()
+    @IsOptional()
+    @IsISO8601()
+    validUntil?: string | null;
+
+    /**
+     * Tope de presupuesto en cents; `null` = sin tope. El signo lo valida el lambda (422): un
+     * presupuesto negativo es un request bien formado que el negocio rechaza.
+     */
+    @Expose()
+    @IsOptional()
+    @IsInt()
+    budgetMaxCents?: number | null;
+}

package/src/loanOfferings/dtos/requests/PromotionEffectInput.ts

@@ -0,0 +1,33 @@
+import { Expose } from 'class-transformer';
+import { IsInt, IsNumber, IsOptional } from 'class-validator';
+
+/**
+ * Efecto de la promoción tal como viaja en el body (alta y edición). Acá se valida solo la FORMA
+ * (que sea número o entero). Las cotas de negocio — rango de cada palanca y que venga al menos una
+ * clave — las valida el lambda con 422: son reglas del negocio sobre un body bien formado.
+ */
+export class PromotionEffectInput {
+    /** Delta NEGATIVO sobre el enganche mínimo (`-0.20` = veinte puntos menos); rango [-1, 0]. */
+    @Expose()
+    @IsOptional()
+    @IsNumber()
+    downPaymentDeltaPct?: number | null;
+
+    /** Bono a la tarjeta PCF, en cents. */
+    @Expose()
+    @IsOptional()
+    @IsInt()
+    pcfBonusCents?: number | null;
+
+    /** TNA que reemplaza a la del plan, hacia abajo (`1.80` = 180%); rango [0, 2.60]. */
+    @Expose()
+    @IsOptional()
+    @IsNumber()
+    tnaOverride?: number | null;
+
+    /** Techo de monto financiable que reemplaza al del plan, en cents. */
+    @Expose()
+    @IsOptional()
+    @IsInt()
+    maxAmountOverrideCents?: number | null;
+}

package/src/loanOfferings/dtos/requests/SimulateCreditPlanRequest.ts

@@ -1,10 +1,14 @@
 import { Expose } from 'class-transformer';
-import { IsInt, IsNumber, IsOptional, Max, Min } from 'class-validator';
+import { IsInt, IsNumber, IsOptional, IsString, Max, Min } from 'class-validator';
 
 /**
  * Body de POST /private/credit-plans/:planId/simulate y query de GET /credit-plans/:planId/simulator.
  * Entradas del simulador de cuota (flow 06 §6.1.4). `productPriceCents` en cents; `downPaymentPct`
  * decimal sobre 1. `customerSciScore` opcional: si viene, se valida contra el rango SCI del plan.
+ *
+ * `storeId` y `productSku` describen DÓNDE y QUÉ se está vendiendo: con ellos el simulador resuelve
+ * qué promoción aplica. Sin ellos, las promociones acotadas a una tienda o a un SKU quedan fuera —
+ * el simulador no adivina, y dar un beneficio que no corresponde es peor que no darlo.
  */
 export class SimulateCreditPlanRequest {
     @Expose()
@@ -29,4 +33,16 @@ export class SimulateCreditPlanRequest {
     @Min(0)
     @Max(100)
     customerSciScore?: number;
+
+    /** Tienda donde se vende. Sin él no se resuelven las promociones acotadas por tienda. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    storeId?: string;
+
+    /** SKU del equipo. Sin él no se resuelven las promociones acotadas por producto. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    productSku?: string;
 }

package/src/loanOfferings/dtos/requests/UpdatePromotionRequest.ts

@@ -0,0 +1,76 @@
+import { Expose, Type } from 'class-transformer';
+import {
+    ArrayNotEmpty,
+    IsArray,
+    IsEnum,
+    IsInt,
+    IsISO8601,
+    IsOptional,
+    IsString,
+    ValidateNested,
+} from 'class-validator';
+import { CreditPlanLevelEnum } from '../../enums/CreditPlanLevelEnum';
+import { PromotionEffectInput } from './PromotionEffectInput';
+
+/**
+ * Body de PUT /promotions/:promotionId — edición parcial (todos los campos opcionales).
+ * Solo se admite sobre `DRAFT` y `PUBLISHED`, y sube `version`. El cambio de estado va por su
+ * endpoint dedicado. `effect` se reemplaza entero cuando viene, no se mergea clave a clave.
+ */
+export class UpdatePromotionRequest {
+    @Expose()
+    @IsOptional()
+    @IsString()
+    name?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    description?: string;
+
+    @Expose()
+    @IsOptional()
+    @ValidateNested()
+    @Type(() => PromotionEffectInput)
+    effect?: PromotionEffectInput;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    segmentId?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ArrayNotEmpty()
+    @IsEnum(CreditPlanLevelEnum, { each: true })
+    targetLevels?: CreditPlanLevelEnum[];
+
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @IsString({ each: true })
+    productSkus?: string[] | null;
+
+    /** Tiendas alcanzadas. `null` o ausente = todas. */
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @IsString({ each: true })
+    storeIds?: string[] | null;
+
+    @Expose()
+    @IsOptional()
+    @IsISO8601()
+    validFrom?: string | null;
+
+    @Expose()
+    @IsOptional()
+    @IsISO8601()
+    validUntil?: string | null;
+
+    @Expose()
+    @IsOptional()
+    @IsInt()
+    budgetMaxCents?: number | null;
+}

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

@@ -0,0 +1,18 @@
+import { PromotionLogEventEnum } from '../../enums/PromotionLogEventEnum';
+import { PromotionStatusEnum } from '../../enums/PromotionStatusEnum';
+
+/**
+ * Fila del tab «Auditoría»: un evento de la bitácora de promociones.
+ * `fromStatus` es `null` en el alta; `reason` solo viene cargado en la pausa.
+ */
+export interface PromotionLogEntryResponse {
+    promotionId: string;
+    promotionName: string;
+    event: PromotionLogEventEnum;
+    occurredAt: string;
+    performedBy: string;
+    fromStatus: PromotionStatusEnum | null;
+    toStatus: PromotionStatusEnum | null;
+    reason: string | null;
+    version: number;
+}

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

@@ -0,0 +1,45 @@
+import { CreditPlanLevelEnum } from '../../enums/CreditPlanLevelEnum';
+import { PromotionEffectKindEnum } from '../../enums/PromotionEffectKindEnum';
+import { PromotionPhaseEnum } from '../../enums/PromotionPhaseEnum';
+import { PromotionStatusEnum } from '../../enums/PromotionStatusEnum';
+import { PromotionEffect } from '../PromotionEffect';
+
+/**
+ * Shape de salida de una promoción (GET / POST / PUT de /promotions).
+ * Montos en cents; porcentajes y TNA en decimal.
+ *
+ * `effectKind` y `phase` son DERIVADOS y no viven en la tabla: el primero sale de las claves de
+ * `effect`, el segundo de las fechas contra hoy y solo cuando el estado es `PUBLISHED`.
+ */
+export interface PromotionResponse {
+    promotionId: string;
+    name: string;
+    description: string;
+    effect: PromotionEffect;
+    /** Derivado de las claves de `effect`; `COMBO` si hay dos o más, `null` si no hay ninguna. */
+    effectKind: PromotionEffectKindEnum | null;
+    segmentId: string;
+    targetLevels: CreditPlanLevelEnum[];
+    /** `null` = alcanza a todos los productos. */
+    productSkus: string[] | null;
+    /** `null` = alcanza a todas las tiendas. Dimensión «Tienda / canal» del alcance. */
+    storeIds: string[] | null;
+    validFrom: string | null;
+    validUntil: string | null;
+    status: PromotionStatusEnum;
+    /** Fase de vigencia derivada; `null` cuando el estado no es `PUBLISHED`. */
+    phase: PromotionPhaseEnum | null;
+    /** Tope de presupuesto; `null` = sin tope. */
+    budgetMaxCents: number | null;
+    budgetConsumedCents: number;
+    creditsGenerated: number;
+    version: number;
+    pausedAt: string | null;
+    pauseReason: string | null;
+    publishedAt: string | null;
+    publishedBy: string | null;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+}

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

@@ -1,3 +1,5 @@
+import { PromotionEffectKindEnum } from '../../enums/PromotionEffectKindEnum';
+
 /**
  * Un renglón de la tabla de amortización (M2 §3.3). Todos los montos en cents.
  */
@@ -14,6 +16,19 @@ export interface AmortizationRowResponse {
     remainingBalanceCents: number;
 }
 
+/**
+ * Promoción que el simulador aplicó a esta cotización. Sin este bloque la cuota cambia y nadie
+ * puede explicar por qué: es lo que hace auditable la regla de que gana una sola promoción.
+ */
+export interface AppliedPromotionResponse {
+    promotionId: string;
+    name: string;
+    /** Versión de la promoción al cotizar — el operador la edita y sube. */
+    version: number;
+    /** Palancas del plan que la promoción pisó. */
+    appliedEffects: PromotionEffectKindEnum[];
+}
+
 /**
  * Resultado del simulador de cuota (POST /private/credit-plans/:planId/simulate,
  * GET /credit-plans/:planId/simulator). Amortización francesa + IVA 16% + comisión de apertura + CAT.
@@ -42,4 +57,9 @@ export interface SimulationResultResponse {
     /** Costo Anual Total (decimal, ej. 2.87 = 287%). Metodología estándar CONDUSEF (supuesto). */
     catAnnual: number;
     schedule: AmortizationRowResponse[];
+    /**
+     * Promoción aplicada, o `null` si ninguna alcanzaba a esta venta. Los montos de arriba YA la
+     * incluyen: es el porqué de la cuota, no un extra a sumar.
+     */
+    appliedPromotion: AppliedPromotionResponse | null;
 }

package/src/loanOfferings/enums/PromotionEffectKindEnum.ts

@@ -0,0 +1,12 @@
+/**
+ * Naturaleza del efecto de una promoción, DERIVADA de las claves presentes en `effect`.
+ * `COMBO` cuando hay dos o más claves. No se persiste: se calcula al responder.
+ * @enum {string}
+ */
+export enum PromotionEffectKindEnum {
+    DOWN_PAYMENT_DELTA = 'DOWN_PAYMENT_DELTA',
+    PCF_BONUS = 'PCF_BONUS',
+    TNA_OVERRIDE = 'TNA_OVERRIDE',
+    MAX_AMOUNT_OVERRIDE = 'MAX_AMOUNT_OVERRIDE',
+    COMBO = 'COMBO',
+}

package/src/loanOfferings/enums/PromotionLogEventEnum.ts

@@ -0,0 +1,12 @@
+/**
+ * Evento de la bitácora de promociones (`<T>LoanPromotionLog_GT`), que alimenta el tab «Auditoría».
+ * @enum {string}
+ */
+export enum PromotionLogEventEnum {
+    CREATE = 'CREATE',
+    PUBLISH = 'PUBLISH',
+    PAUSE = 'PAUSE',
+    RESUME = 'RESUME',
+    EXPIRE = 'EXPIRE',
+    UPDATE = 'UPDATE',
+}

package/src/loanOfferings/enums/PromotionPhaseEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * Fase de vigencia de una promoción PUBLICADA, derivada de `validFrom`/`validUntil` contra hoy.
+ * No se persiste — así no hace falta un cron que mueva estados a medianoche. `null` cuando el
+ * estado persistido no es `PUBLISHED`.
+ * @enum {string}
+ */
+export enum PromotionPhaseEnum {
+    SCHEDULED = 'SCHEDULED',
+    ACTIVE = 'ACTIVE',
+    EXPIRED = 'EXPIRED',
+}

package/src/loanOfferings/enums/PromotionStatusEnum.ts

@@ -0,0 +1,12 @@
+/**
+ * Estado PERSISTIDO de una promoción del motor (portal-admin-sk-promociones).
+ * `EXPIRED` es terminal. La «fase» que ve el operador (programada / activa / vencida) NO se guarda:
+ * se deriva de las fechas — ver `PromotionPhaseEnum`.
+ * @enum {string}
+ */
+export enum PromotionStatusEnum {
+    DRAFT = 'DRAFT',
+    PUBLISHED = 'PUBLISHED',
+    PAUSED = 'PAUSED',
+    EXPIRED = 'EXPIRED',
+}