@fiado/type-kit 3.471.0 → 3.473.0

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

@@ -0,0 +1,9 @@
+import { DiscountCode } from '../DiscountCode';
+
+export type CreateDiscountCodeResponse = DiscountCode;
+export type ChangeDiscountCodeStatusResponse = DiscountCode;
+
+export interface ListDiscountCodesResponse {
+    items: DiscountCode[];
+    nextToken: string | null;
+}

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

@@ -0,0 +1,35 @@
+import { SalePromotion } from '../SalePromotion';
+import { SalePromotionLogEntry } from '../SalePromotionLogEntry';
+
+export type CreateSalePromotionResponse = SalePromotion;
+export type GetSalePromotionResponse = SalePromotion;
+export type UpdateSalePromotionResponse = SalePromotion;
+export type ChangeSalePromotionStatusResponse = SalePromotion;
+
+/** Fila del listado de Admin VL: la promo más sus canjes de los últimos 30 días. */
+export interface SalePromotionListItem extends SalePromotion {
+    redemptionsLast30Days: number;
+}
+
+/** KPIs de la cabecera de «Promos venta». */
+export interface SalePromotionKpis {
+    activeCount: number;
+    expiringIn7DaysCount: number;
+    scheduledCount: number;
+    pausedCount: number;
+    redemptionsLast30Days: number;
+    /** Presupuesto consumido sobre el tope, en puntos base, de las promos con tope (`computeBudgetUsedBps`); `null` si ninguna tiene. */
+    budgetUsedBps: number | null;
+}
+
+export interface ListSalePromotionsResponse {
+    items: SalePromotionListItem[];
+    kpis: SalePromotionKpis;
+    nextToken: string | null;
+}
+
+/** Página JSON del historial; con `format=CSV` el endpoint responde `text/csv`. */
+export interface ListSalePromotionLogResponse {
+    items: SalePromotionLogEntry[];
+    nextToken: string | null;
+}

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

@@ -0,0 +1,115 @@
+import { CouponScopeEnum } from '../../enums/CouponScopeEnum';
+import { CouponStatusEnum } from '../../enums/CouponStatusEnum';
+import { EntitlementKindEnum } from '../../enums/EntitlementKindEnum';
+import { EntitlementStateEnum } from '../../enums/EntitlementStateEnum';
+import { RetailPromotionsErrorCodeEnum } from '../../enums/RetailPromotionsErrorCodeEnum';
+import { SaleCouponAvailabilityEnum } from '../../enums/SaleCouponAvailabilityEnum';
+import { SalePromotionLeverEnum } from '../../enums/SalePromotionLeverEnum';
+import { DiscountValue } from '../DiscountValue';
+import { LinePromotionDiscount } from '../LinePromotionDiscount';
+import { SalePromotionLevers, SalePromotionScope } from '../SalePromotionLevers';
+
+/** Promo vigente en la tienda de la sesión, para los chips de «Elige el teléfono». */
+export interface StoreSalePromotionItem {
+    promotionId: string;
+    version: number;
+    name: string;
+    customerText: string;
+    levers: SalePromotionLevers;
+    /** Para cruzar con cada equipo; todo `null` = fila «Toda la tienda». */
+    scope: SalePromotionScope;
+}
+
+export interface ListStoreSalePromotionsResponse {
+    items: StoreSalePromotionItem[];
+}
+
+/** Opción de regalo con su existencia en la tienda; sin existencia se muestra en gris. */
+export interface GiftOption {
+    sku: string;
+    name: string;
+    listPriceCents: number;
+    inStock: boolean;
+}
+
+/** Lo que se entrega al cerrar («Después en la venta»). `quantity`: recargas o meses de garantía. */
+export interface AfterSaleBenefit {
+    lever: SalePromotionLeverEnum;
+    amountCents: number | null;
+    quantity: number | null;
+}
+
+/** Promo que aplica a la sesión, con el desglose que tendría al apartarla. */
+export interface EvaluatedSalePromotion {
+    promotionId: string;
+    version: number;
+    name: string;
+    customerText: string;
+    levers: SalePromotionLeverEnum[];
+    lines: LinePromotionDiscount[];
+    totalDiscountCents: number;
+    giftOptions: GiftOption[];
+    giftChooseCount: number | null;
+    afterSale: AfterSaleBenefit[];
+}
+
+/** Resultado del código tecleado: si no aplica, `rejectionCode` dice por qué. */
+export interface EvaluatedDiscountCode {
+    codeText: string;
+    applicable: boolean;
+    rejectionCode: RetailPromotionsErrorCodeEnum | null;
+    lines: LinePromotionDiscount[];
+    totalDiscountCents: number;
+}
+
+export interface EvaluateSalePromotionsResponse {
+    promotions: EvaluatedSalePromotion[];
+    discountCode: EvaluatedDiscountCode | null;
+}
+
+/** Lo que quedó apartado y escrito en la sesión. */
+export interface HoldSalePromotionResponse {
+    sessionId: string;
+    promotionId: string | null;
+    promotionVersion: number | null;
+    discountCode: string | null;
+    giftSkus: string[];
+    lines: LinePromotionDiscount[];
+    totalDiscountCents: number;
+}
+
+/** `released: false` = no había apartado; soltar es idempotente. */
+export interface ReleaseSalePromotionResponse {
+    sessionId: string;
+    released: boolean;
+}
+
+/** Respuesta del privado que llama el wizard al cancelar la sesión o la venta. */
+export interface PrivateReleaseSalePromotionResponse {
+    sessionId: string;
+    released: boolean;
+}
+
+export interface SaleCoupon {
+    codeText: string;
+    discount: DiscountValue;
+    validUntil: string;
+    scope: CouponScopeEnum;
+    status: CouponStatusEnum;
+}
+
+/** Entrega posterior a la venta. `quantity`: recargas o meses de garantía. */
+export interface SaleEntitlement {
+    kind: EntitlementKindEnum;
+    state: EntitlementStateEnum;
+    amountCents: number | null;
+    quantity: number | null;
+}
+
+/** Cupón y «lo que se lleva» de una venta cerrada (publicGetSaleCoupon). */
+export interface GetSaleCouponResponse {
+    saleId: string;
+    availability: SaleCouponAvailabilityEnum;
+    coupon: SaleCoupon | null;
+    entitlements: SaleEntitlement[];
+}

package/src/retailPromotions/enums/CouponScopeEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * Dónde vale el cupón que emite la venta.
+ * @enum {string}
+ */
+export enum CouponScopeEnum {
+    /** Toda la cadena del retailer. */
+    CHAIN = 'CHAIN',
+    ISSUING_STORE = 'ISSUING_STORE',
+    /** Las tiendas del alcance de la promo que lo emitió. */
+    PROMOTION_STORES = 'PROMOTION_STORES',
+}

package/src/retailPromotions/enums/CouponStatusEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * Estado del cupón emitido por una venta. `USED` puede volver a `ACTIVE` o `EXPIRED` si se
+ * cancela la venta donde se canjeó.
+ * @enum {string}
+ */
+export enum CouponStatusEnum {
+    ACTIVE = 'ACTIVE',
+    USED = 'USED',
+    EXPIRED = 'EXPIRED',
+    VOIDED = 'VOIDED',
+}

package/src/retailPromotions/enums/DiscountCodeOriginEnum.ts

@@ -0,0 +1,8 @@
+/**
+ * Origen de un código: creado por Admin VL o cupón emitido por una venta.
+ * @enum {string}
+ */
+export enum DiscountCodeOriginEnum {
+    ADMIN = 'ADMIN',
+    SALE_COUPON = 'SALE_COUPON',
+}

package/src/retailPromotions/enums/DiscountCodeStatusEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * Estado de un código de descuento creado en Admin VL.
+ * @enum {string}
+ */
+export enum DiscountCodeStatusEnum {
+    ACTIVE = 'ACTIVE',
+    /** Llegó a sus usos totales. */
+    EXHAUSTED = 'EXHAUSTED',
+    EXPIRED = 'EXPIRED',
+    VOIDED = 'VOIDED',
+}

package/src/retailPromotions/enums/DiscountCodeTransitionEnum.ts

@@ -0,0 +1,7 @@
+/**
+ * Acción de Admin VL sobre un código o cupón. Hoy solo anular.
+ * @enum {string}
+ */
+export enum DiscountCodeTransitionEnum {
+    VOID = 'VOID',
+}

package/src/retailPromotions/enums/DiscountTypeEnum.ts

@@ -0,0 +1,8 @@
+/**
+ * Tipo de descuento: monto fijo en centavos o porcentaje en puntos base (1000 = 10%).
+ * @enum {string}
+ */
+export enum DiscountTypeEnum {
+    AMOUNT = 'AMOUNT',
+    PERCENTAGE = 'PERCENTAGE',
+}

package/src/retailPromotions/enums/EntitlementKindEnum.ts

@@ -0,0 +1,9 @@
+/**
+ * Tipo de entrega posterior a la venta.
+ * @enum {string}
+ */
+export enum EntitlementKindEnum {
+    WALLET = 'WALLET',
+    WARRANTY = 'WARRANTY',
+    AIRTIME = 'AIRTIME',
+}

package/src/retailPromotions/enums/EntitlementStateEnum.ts

@@ -0,0 +1,13 @@
+/**
+ * Estado de una entrega posterior a la venta (Wallet, garantía, tiempo aire).
+ * @enum {string}
+ */
+export enum EntitlementStateEnum {
+    PENDING = 'PENDING',
+    /** Reclamada con lease; hay una llamada al processor en curso. */
+    IN_FLIGHT = 'IN_FLIGHT',
+    SETTLED = 'SETTLED',
+    /** No se sabe si movió dinero: se concilia a mano, sin reintento. */
+    UNVERIFIED = 'UNVERIFIED',
+    VOID = 'VOID',
+}

package/src/retailPromotions/enums/GiftModeEnum.ts

@@ -0,0 +1,8 @@
+/**
+ * Cómo se define el regalo: lista cerrada de SKUs o gama (categoría y precio máximo).
+ * @enum {string}
+ */
+export enum GiftModeEnum {
+    LIST = 'LIST',
+    RANGE = 'RANGE',
+}

package/src/retailPromotions/enums/PromotionAppliesToEnum.ts

@@ -0,0 +1,9 @@
+/**
+ * Con qué financiera aplica una promo o un código. Sin valor, el lambda asume `SUREKEEP_ONLY`.
+ * @enum {string}
+ */
+export enum PromotionAppliesToEnum {
+    SUREKEEP_ONLY = 'SUREKEEP_ONLY',
+    /** También cuando el teléfono se deriva a otra financiera y la venta cuenta como contado. */
+    ANY_FINANCIER = 'ANY_FINANCIER',
+}

package/src/retailPromotions/enums/RetailPromotionsErrorCodeEnum.ts

@@ -0,0 +1,23 @@
+/**
+ * Codes de error de retail-promotions-business; el status de cada uno está en
+ * `RETAIL_PROMOTIONS_ERROR_HTTP_STATUS`. Las clases `DomainError` viven en el lambda.
+ * @enum {string}
+ */
+export enum RetailPromotionsErrorCodeEnum {
+    INVALID_PROMOTION_TRANSITION = 'INVALID_PROMOTION_TRANSITION',
+    CODE_TEXT_TAKEN = 'CODE_TEXT_TAKEN',
+    PROMOTION_NOT_ACTIVE = 'PROMOTION_NOT_ACTIVE',
+    PROMOTION_NOT_APPLICABLE = 'PROMOTION_NOT_APPLICABLE',
+    CUSTOMER_NOT_IDENTIFIED = 'CUSTOMER_NOT_IDENTIFIED',
+    GIFT_NOT_ALLOWED = 'GIFT_NOT_ALLOWED',
+    INSUFFICIENT_STOCK = 'INSUFFICIENT_STOCK',
+    CODE_NOT_FOUND = 'CODE_NOT_FOUND',
+    CODE_NOT_APPLICABLE = 'CODE_NOT_APPLICABLE',
+    CODE_NOT_OWNED = 'CODE_NOT_OWNED',
+    CODE_NOT_ACTIVE = 'CODE_NOT_ACTIVE',
+    CODE_EXHAUSTED = 'CODE_EXHAUSTED',
+    CODE_ALREADY_APPLIED = 'CODE_ALREADY_APPLIED',
+    DISCOUNT_AFTER_QUOTE = 'DISCOUNT_AFTER_QUOTE',
+    INVALID_SALE_PROMOTION = 'INVALID_SALE_PROMOTION',
+    INVALID_DISCOUNT_CODE = 'INVALID_DISCOUNT_CODE',
+}

package/src/retailPromotions/enums/SaleCouponAvailabilityEnum.ts

@@ -0,0 +1,10 @@
+/**
+ * Si la venta cerrada ya tiene su cupón: `GENERATING` mientras la cola no lo emite.
+ * @enum {string}
+ */
+export enum SaleCouponAvailabilityEnum {
+    GENERATING = 'GENERATING',
+    READY = 'READY',
+    /** La venta no da cupón. */
+    NONE = 'NONE',
+}

package/src/retailPromotions/enums/SalePromotionLeverEnum.ts

@@ -0,0 +1,13 @@
+/**
+ * Las 7 palancas combinables de una promo de venta.
+ * @enum {string}
+ */
+export enum SalePromotionLeverEnum {
+    DEVICE_DISCOUNT = 'DEVICE_DISCOUNT',
+    ACCESSORY_DISCOUNT = 'ACCESSORY_DISCOUNT',
+    GIFT = 'GIFT',
+    COUPON = 'COUPON',
+    AIRTIME = 'AIRTIME',
+    EXTENDED_WARRANTY = 'EXTENDED_WARRANTY',
+    WALLET_BONUS = 'WALLET_BONUS',
+}

package/src/retailPromotions/enums/SalePromotionLogEventEnum.ts

@@ -0,0 +1,14 @@
+/**
+ * Evento del historial de promos de venta. Los automáticos (autopausa, reanudación, vencimiento)
+ * usan el mismo evento con autor `system`.
+ * @enum {string}
+ */
+export enum SalePromotionLogEventEnum {
+    CREATE = 'CREATE',
+    UPDATE = 'UPDATE',
+    PUBLISH = 'PUBLISH',
+    PAUSE = 'PAUSE',
+    RESUME = 'RESUME',
+    EXPIRE = 'EXPIRE',
+    ARCHIVE = 'ARCHIVE',
+}

package/src/retailPromotions/enums/SalePromotionLogFormatEnum.ts

@@ -0,0 +1,5 @@
+/** Formato de salida del historial: página JSON o exportación CSV. */
+export enum SalePromotionLogFormatEnum {
+    JSON = 'JSON',
+    CSV = 'CSV',
+}

package/src/retailPromotions/enums/SalePromotionPhaseEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * Fase derivada de la vigencia (hora CDMX) de una promo `ACTIVE`; no se persiste.
+ * @enum {string}
+ */
+export enum SalePromotionPhaseEnum {
+    /** Activa con inicio futuro. */
+    SCHEDULED = 'SCHEDULED',
+    LIVE = 'LIVE',
+    /** Vigente y termina en los próximos 7 días. */
+    EXPIRING_SOON = 'EXPIRING_SOON',
+}

package/src/retailPromotions/enums/SalePromotionStatusEnum.ts

@@ -0,0 +1,12 @@
+/**
+ * Estado persistido de una promo de venta. Programada, permanente y vencida-por-fecha se derivan
+ * de la vigencia; `ARCHIVED` la oculta del listado salvo en el filtro «Archivadas».
+ * @enum {string}
+ */
+export enum SalePromotionStatusEnum {
+    DRAFT = 'DRAFT',
+    ACTIVE = 'ACTIVE',
+    PAUSED = 'PAUSED',
+    EXPIRED = 'EXPIRED',
+    ARCHIVED = 'ARCHIVED',
+}

package/src/retailPromotions/enums/SalePromotionTransitionEnum.ts

@@ -0,0 +1,13 @@
+/**
+ * Acción que pide Admin VL sobre una promo de venta. El destino lo resuelve
+ * `resolveSalePromotionTransition`; una transición no permitida es `INVALID_PROMOTION_TRANSITION`.
+ * @enum {string}
+ */
+export enum SalePromotionTransitionEnum {
+    PUBLISH = 'PUBLISH',
+    PAUSE = 'PAUSE',
+    RESUME = 'RESUME',
+    /** Fin ahora. Que no aplique a una promo permanente lo valida el lambda. */
+    EXPIRE = 'EXPIRE',
+    ARCHIVE = 'ARCHIVE',
+}

package/src/retailPromotions/helpers/computeBudgetUsedBps.ts

@@ -0,0 +1,15 @@
+import { SalePromotion } from '../dtos/SalePromotion';
+
+/** % de presupuesto consumido en puntos base sobre las promos con tope; `null` si ninguna tiene tope. */
+export function computeBudgetUsedBps(
+    promotions: Pick<SalePromotion, 'budgetMaxCents' | 'budgetConsumedCents'>[],
+): number | null {
+    let maxCents = 0;
+    let consumedCents = 0;
+    for (const { budgetMaxCents, budgetConsumedCents } of promotions) {
+        if (budgetMaxCents === null) continue;
+        maxCents += budgetMaxCents;
+        consumedCents += budgetConsumedCents;
+    }
+    return maxCents > 0 ? Math.floor((consumedCents * 10000) / maxCents) : null;
+}

package/src/retailPromotions/helpers/resolveSalePromotionTransition.ts

@@ -0,0 +1,12 @@
+import { SALE_PROMOTION_TRANSITIONS } from '../constants/salePromotionTransitions';
+import { SalePromotionStatusEnum } from '../enums/SalePromotionStatusEnum';
+import { SalePromotionTransitionEnum } from '../enums/SalePromotionTransitionEnum';
+
+/** Estado destino de aplicar la transición, o `null` si no se permite desde `from`. */
+export function resolveSalePromotionTransition(
+    from: SalePromotionStatusEnum,
+    transition: SalePromotionTransitionEnum,
+): SalePromotionStatusEnum | null {
+    const rule = SALE_PROMOTION_TRANSITIONS[transition];
+    return rule.from.includes(from) ? rule.to : null;
+}

package/src/retailPromotions/index.ts

@@ -0,0 +1,55 @@
+// Enums
+export * from './enums/SalePromotionStatusEnum';
+export * from './enums/SalePromotionTransitionEnum';
+export * from './enums/SalePromotionPhaseEnum';
+export * from './enums/SalePromotionLeverEnum';
+export * from './enums/SalePromotionLogEventEnum';
+export * from './enums/SalePromotionLogFormatEnum';
+export * from './enums/DiscountTypeEnum';
+export * from './enums/GiftModeEnum';
+export * from './enums/PromotionAppliesToEnum';
+export * from './enums/CouponScopeEnum';
+export * from './enums/CouponStatusEnum';
+export * from './enums/DiscountCodeStatusEnum';
+export * from './enums/DiscountCodeOriginEnum';
+export * from './enums/DiscountCodeTransitionEnum';
+export * from './enums/EntitlementStateEnum';
+export * from './enums/EntitlementKindEnum';
+export * from './enums/SaleCouponAvailabilityEnum';
+export * from './enums/RetailPromotionsErrorCodeEnum';
+
+// Constantes y helpers puros
+export * from './constants/retailPromotionsErrorHttpStatus';
+export * from './constants/salePromotionTransitions';
+export * from './constants/bonusPreMoney';
+export * from './helpers/resolveSalePromotionTransition';
+export * from './helpers/computeBudgetUsedBps';
+
+// Entidades del dominio
+export * from './dtos/DiscountValue';
+export * from './dtos/SalePromotionLevers';
+export * from './dtos/SalePromotion';
+export * from './dtos/SalePromotionLogEntry';
+export * from './dtos/DiscountCode';
+export * from './dtos/LinePromotionDiscount';
+
+// Request DTOs
+export * from './dtos/requests/DiscountValueInput';
+export * from './dtos/requests/SalePromotionLeversInput';
+export * from './dtos/requests/SalePromotionScopeInput';
+export * from './dtos/requests/CreateSalePromotionRequest';
+export * from './dtos/requests/UpdateSalePromotionRequest';
+export * from './dtos/requests/ChangeSalePromotionStatusRequest';
+export * from './dtos/requests/ListSalePromotionsQuery';
+export * from './dtos/requests/ListSalePromotionLogQuery';
+export * from './dtos/requests/CreateDiscountCodeRequest';
+export * from './dtos/requests/ListDiscountCodesQuery';
+export * from './dtos/requests/ChangeDiscountCodeStatusRequest';
+export * from './dtos/requests/ListStoreSalePromotionsQuery';
+export * from './dtos/requests/EvaluateSalePromotionsRequest';
+export * from './dtos/requests/HoldSalePromotionRequest';
+
+// Response DTOs
+export * from './dtos/responses/SalePromotionCrudResponses';
+export * from './dtos/responses/DiscountCodeResponses';
+export * from './dtos/responses/WizardSalePromotionResponses';

package/src/retailWizard/dtos/Sale.ts

@@ -27,18 +27,18 @@ export interface Sale {
   skus?: string[];
   /** La cancelación aún no confirma la devolución al inventario. */
   inventoryReturnPending?: boolean;
+  /** Venta de la saga: el inventario se aplica y se devuelve por la cola, no por HTTP. */
+  inventoryViaQueue?: boolean;
+  /** Promo de venta congelada al cerrar; `null` = ninguna. */
+  salePromotionId?: string | null;
+  salePromotionVersion?: number | null;
   /** IMEI consumido del silo también en contado (local-first); null en EXTERNAL_REFERRAL (D15). */
   imei: string | null;
-  /**
-   * Lo COBRADO en caja al cerrar. En contado == precio del equipo (lo garantiza `registerPayment`);
-   * en crédito es SOLO el enganche. ⚠️ Su significado es contrato de `SaleCompletedV1` (La Central,
-   * comisión F4): no redefinir — el precio del equipo viaja aparte en `equipmentPriceCents`. 0 en
-   * EXTERNAL_REFERRAL.
-   */
+  /** Lo cobrado en caja al cerrar: enganche + lo no financiado; 0 en EXTERNAL_REFERRAL. Contrato de `SaleCompletedV1`. */
   amountCents: number;
   /**
-   * Precio de lista del equipo al cerrar (de la reserva de la sesión). En contado coincide con
-   * `amountCents`; en crédito es el precio full financiado. `null` en ventas anteriores al campo.
+   * Ancla neta al cerrar (precio − discountCents de la ancla); base de comisión.
+   * `null` en ventas anteriores al campo.
    */
   equipmentPriceCents: number | null;
   /** Enganche cobrado (solo ventas CREDIT; `null` en contado/externa). */

package/src/retailWizard/dtos/SaleLine.ts

@@ -1,9 +1,10 @@
 import type { SoldLineComponent } from '../../retailCatalog/dtos/responses/SellStockResponse';
 import type { LinePaymentTypeEnum } from '../enums/LinePaymentTypeEnum';
 import type { WizardLineProduct } from './WizardLineProduct';
+import type { WizardLinePromotionFields } from './WizardLinePromotionFields';
 
 /** Línea de una venta cerrada; un producto suelto es un solo componente. */
-export interface SaleLine {
+export interface SaleLine extends WizardLinePromotionFields {
     lineId: string;
     sku: string;
     qty: number;
@@ -12,6 +13,8 @@ export interface SaleLine {
     /** Llave del registro PRICE# del que salió el precio. */
     priceSk: string;
     paymentType: LinePaymentTypeEnum;
+    /** Parte financiada de la línea, congelada en la venta. */
+    financedCents?: number;
     components: SoldLineComponent[];
     product?: WizardLineProduct | null;
 }

package/src/retailWizard/dtos/WizardFinancingPreview.ts

@@ -0,0 +1,12 @@
+/** Parte financiada de una línea en el reparto provisional. */
+export interface WizardFinancingPreviewLine {
+    lineId: string;
+    financedCents: number;
+}
+
+/** Reparto provisional de la sesión; se calcula al leer y no se persiste. */
+export interface WizardFinancingPreview {
+    /** Tope de extras financiables: floor(30% × ancla neta). */
+    capCents: number;
+    lines: WizardFinancingPreviewLine[];
+}

package/src/retailWizard/dtos/WizardGiftLine.ts

@@ -0,0 +1,9 @@
+import type { WizardLineRoleEnum } from '../enums/WizardLineRoleEnum';
+import type { WizardReservedLine } from './WizardReservedLine';
+
+/** Línea GIFT: siempre ligada a un ancla y con el precio de lista que se regala. */
+export type WizardGiftLine = WizardReservedLine & {
+    role: WizardLineRoleEnum.GIFT;
+    linkedLineId: string;
+    originalPriceCents: number;
+};

package/src/retailWizard/dtos/WizardLinePromotionFields.ts

@@ -0,0 +1,16 @@
+import type { WizardLineRoleEnum } from '../enums/WizardLineRoleEnum';
+
+/** Campos de Promociones en la línea de sesión y de venta; solo los escribe su endpoint M2M. */
+export interface WizardLinePromotionFields {
+    role?: WizardLineRoleEnum;
+    promotionId?: string;
+    promotionVersion?: number;
+    /** Línea ancla a la que va ligado el regalo. */
+    linkedLineId?: string;
+    /** Solo en la línea ancla. */
+    discountCode?: string;
+    /** Descuento total de la línea; neto = basePriceCents × qty − discountCents. */
+    discountCents?: number;
+    /** Precio antes del descuento; en un regalo, el valor de lista con la línea a $0. */
+    originalPriceCents?: number;
+}

package/src/retailWizard/dtos/WizardReservedLine.ts

@@ -4,9 +4,10 @@ import type { LinePaymentTypeEnum } from '../enums/LinePaymentTypeEnum';
 import type { WizardLineStatusEnum } from '../enums/WizardLineStatusEnum';
 import type { WizardLineIdentifiers } from './WizardLineIdentifiers';
 import type { WizardLineProduct } from './WizardLineProduct';
+import type { WizardLinePromotionFields } from './WizardLinePromotionFields';
 
 /** Línea de la venta en curso; los campos de precio son `null` mientras la línea está PENDING. */
-export interface WizardReservedLine {
+export interface WizardReservedLine extends WizardLinePromotionFields {
     lineId: string;
     sku: string;
     qty: number;
@@ -27,6 +28,8 @@ export interface WizardReservedLine {
     paymentType: LinePaymentTypeEnum | null;
     /** Ítems que la línea suma al tope de 100 de la venta. */
     sellItemCost: number | null;
+    /** Parte financiada de la línea; se escribe al cotizar y se congela con el crédito. */
+    financedCents?: number;
     mdmEnabled?: boolean;
     mdmProvider?: MdmProviderEnum | null;
     /** Solo si la línea es un kit. */

package/src/retailWizard/dtos/WizardSession.ts

@@ -6,6 +6,7 @@ import type { ExternalProviderEnum } from '../enums/ExternalProviderEnum';
 import type { OccupationEnum } from '../enums/OccupationEnum';
 import type { WizardBlockedSummary } from './WizardBlocked';
 import type { WizardConsents } from './WizardConsents';
+import type { WizardFinancingPreview } from './WizardFinancingPreview';
 import type { WizardLoan } from './WizardLoan';
 import type { WizardPayment } from './WizardPayment';
 import type { WizardProduct } from './WizardProduct';
@@ -117,6 +118,15 @@ export interface WizardSession {
   reservedLines?: WizardReservedLine[];
   /** Línea elegida para financiar; `null` si la venta es de contado o aún no se elige. */
   financedLineId?: string | null;
+  /** Reparto provisional mientras haya líneas; se calcula al leer, no se persiste. */
+  financingPreview?: WizardFinancingPreview | null;
+  /** Marca de la saga: todas las piezas rastreadas de las líneas vivas quedaron HELD. */
+  piecesHeldAt?: string | null;
+  /** Promo de venta que fijó Promociones; `null` = ninguna. */
+  salePromotionId?: string | null;
+  salePromotionVersion?: number | null;
+  /** Enganche cobrado que queda por reembolsar tras cancelar. */
+  refundPendingCents?: number;
   paymentMethod: PaymentMethodEnum | null;
   externalProvider: ExternalProviderEnum | null;
   /** Folio de cobro server-side (D11), idempotente, sobrevive al volver atrás. */

package/src/retailWizard/dtos/requests/AddProductRequest.ts

@@ -1,5 +1,5 @@
 import { Expose } from 'class-transformer';
-import { IsInt, IsOptional, IsString, Min } from 'class-validator';
+import { IsInt, IsOptional, IsString, Min, MinLength } from 'class-validator';
 
 /**
  * POST /wizard/sessions/:id/product — agrega una línea a la venta y reserva sus piezas en el catálogo.
@@ -27,4 +27,11 @@ export class AddProductRequest {
   @IsInt()
   @Min(1)
   qty?: number;
+
+  /** Línea viva que este kit reemplaza («Cambiar por el kit»). */
+  @Expose()
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  replacesLineId?: string;
 }