@fiado/type-kit 3.471.0 → 3.473.0

package/bin/retailWizard/index.js

@@ -41,6 +41,7 @@ __exportStar(require("./enums/BlockedReasonEnum"), exports);
 __exportStar(require("./enums/BlockedCategoryEnum"), exports);
 __exportStar(require("./enums/WizardLineStatusEnum"), exports);
 __exportStar(require("./enums/LinePaymentTypeEnum"), exports);
+__exportStar(require("./enums/WizardLineRoleEnum"), exports);
 // DTOs anidados
 __exportStar(require("./dtos/WizardConsents"), exports);
 __exportStar(require("./dtos/WizardPayment"), exports);
@@ -57,7 +58,10 @@ __exportStar(require("./dtos/WizardResumeTarget"), exports);
 __exportStar(require("./dtos/WizardBlocked"), exports);
 __exportStar(require("./dtos/WizardLineProduct"), exports);
 __exportStar(require("./dtos/WizardLineIdentifiers"), exports);
+__exportStar(require("./dtos/WizardLinePromotionFields"), exports);
+__exportStar(require("./dtos/WizardFinancingPreview"), exports);
 __exportStar(require("./dtos/WizardReservedLine"), exports);
+__exportStar(require("./dtos/WizardGiftLine"), exports);
 __exportStar(require("./dtos/SaleLine"), exports);
 // Entidades principales (shapes de estado/persistencia — planas)
 __exportStar(require("./dtos/WizardSession"), exports);
@@ -79,6 +83,10 @@ __exportStar(require("./dtos/requests/KycManualRequest"), exports);
 __exportStar(require("./dtos/requests/ProofOfAddressPrepareRequest"), exports);
 __exportStar(require("./dtos/requests/OccupationRequest"), exports);
 __exportStar(require("./dtos/requests/AddProductRequest"), exports);
+__exportStar(require("./dtos/requests/PinSessionPiecesRequest"), exports);
+__exportStar(require("./dtos/requests/ApplyLinePromotionRequest"), exports);
+__exportStar(require("./dtos/requests/SetAnchorGiftsRequest"), exports);
+__exportStar(require("./dtos/requests/ApplySalePromotionRequest"), exports);
 __exportStar(require("./dtos/requests/DeleteProductRequest"), exports);
 __exportStar(require("./dtos/requests/SetPaymentMethodRequest"), exports);
 __exportStar(require("./dtos/requests/ExternalReferralRequest"), exports);
@@ -160,7 +168,13 @@ __exportStar(require("./events/SaleCancelledV1"), exports);
 __exportStar(require("./events/SaleCompletedV2"), exports);
 __exportStar(require("./events/SaleCancelledV2"), exports);
 __exportStar(require("./events/SessionExpiredV1"), exports);
+__exportStar(require("./enums/RetailPromotionInboundMessageTypeEnum"), exports);
+__exportStar(require("./events/RetailPromotionInboundMessage"), exports);
+__exportStar(require("./events/RetailCommissionInboundMessage"), exports);
 // Lookup privado por lote (GET /private/wizard-sessions/batch)
 __exportStar(require("./enums/WizardSessionLookupStatusEnum"), exports);
 __exportStar(require("./dtos/WizardSessionLookupEntry"), exports);
 __exportStar(require("./dtos/responses/WizardSessionLookupResponse"), exports);
+// M2M de Promociones (lectura privada de la sesión y regalo)
+__exportStar(require("./dtos/responses/PrivateWizardSessionResponse"), exports);
+__exportStar(require("./dtos/responses/SetAnchorGiftsResponse"), exports);

package/package.json

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

package/src/common/index.ts

@@ -1,6 +1,9 @@
 //decorators
 export * from './decorators/Trim';
 
+//validators
+export * from './validators/IsStringValueRecord';
+
 //dtos
 export * from './dtos/ProcessValidationResultDto';
 

package/src/common/validators/IsStringValueRecord.ts

@@ -0,0 +1,13 @@
+import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+
+// Valida que un objeto sea un mapa clave → string.
+@ValidatorConstraint({ name: 'IsStringValueRecord', async: false })
+export class IsStringValueRecord implements ValidatorConstraintInterface {
+    validate(value: unknown, _args: ValidationArguments): boolean {
+        if (!value || typeof value !== 'object') return false;
+        return Object.values(value as Record<string, unknown>).every(v => typeof v === 'string');
+    }
+    defaultMessage(_args: ValidationArguments): string {
+        return 'All values in variables must be strings';
+    }
+}

package/src/index.ts

@@ -122,6 +122,9 @@ export * as RetailCustomer from './retailCustomer';
 // RetailWizard: DTOs/enums del lambda retail-wizard-business (comp 04 — wizard de venta de contado:
 // saga de sesión, OTP, KYC, venta y prospectos; SureKeep Fase 2 — pista Retail).
 export * as RetailWizard from './retailWizard';
+// RetailPromotions: DTOs/enums de retail-promotions-business (promos de venta, códigos de descuento y
+// cupones de VentasLuga). Porcentajes en puntos base, dinero en centavos.
+export * as RetailPromotions from './retailPromotions';
 export * as DatalakeQuery from './datalakeQuery';
 // LoanConfig: DTOs/enums del lambda loan-config-business (comp 09 — parámetros operativos del SOFOM).
 export * as LoanConfig from './loanConfig';

package/src/messagesConnector/validators/IsStringValueRecord.ts

@@ -1,12 +1,2 @@
-import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
-
-@ValidatorConstraint({ name: 'IsStringValueRecord', async: false })
-export class IsStringValueRecord implements ValidatorConstraintInterface {
-    validate(value: unknown, _args: ValidationArguments): boolean {
-        if (!value || typeof value !== 'object') return false;
-        return Object.values(value as Record<string, unknown>).every(v => typeof v === 'string');
-    }
-    defaultMessage(_args: ValidationArguments): string {
-        return 'All values in variables must be strings';
-    }
-}
+// Movido a common: se reexporta para no romper a quien importa desde messagesConnector.
+export { IsStringValueRecord } from '../../common/validators/IsStringValueRecord';

package/src/platformRbac/dtos/CreateTenantUserRequest.ts

@@ -1,6 +1,7 @@
 import { Expose } from 'class-transformer';
-import { IsEmail, IsEnum, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+import { IsEmail, IsEnum, IsNotEmpty, IsObject, IsOptional, IsString, Validate } from 'class-validator';
 import { PermissionScope } from '../enums/PermissionScope';
+import { IsStringValueRecord } from '../../common/validators/IsStringValueRecord';
 
 /**
  * Body del POST /internal/tenants/{tenantId}/users (endpoint privado, VPC/ANONIMUS). `tenantId` viaja en el path.
@@ -11,6 +12,7 @@ import { PermissionScope } from '../enums/PermissionScope';
  * - Idempotente por identidad Cognito.
  * - `scope`/`scopeRef` = grant del rol (ej. LEVEL_3 + storeId para un vendedor de tienda).
  * - `createdBy` = cognitoSub del admin real (audit + grantedBy del assignment).
+ * - `customFields` = valores de los campos personalizados del tenant; si el correo ya tiene usuario, se fusionan.
  */
 export class CreateTenantUserRequest {
     @Expose() @IsEmail() email!: string;
@@ -19,4 +21,9 @@ export class CreateTenantUserRequest {
     @Expose() @IsEnum(PermissionScope) scope!: PermissionScope;
     @Expose() @IsString() @IsNotEmpty() scopeRef!: string;
     @Expose() @IsString() @IsNotEmpty() createdBy!: string;
+    @Expose()
+    @IsOptional()
+    @IsObject()
+    @Validate(IsStringValueRecord, { message: 'customFields: todos los valores deben ser string' })
+    customFields?: { [key: string]: string };
 }

package/src/platformRbac/dtos/UpdateTenantUserRequest.ts

@@ -1,11 +1,17 @@
 import { Expose } from 'class-transformer';
-import { IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
+import { IsNotEmpty, IsObject, IsOptional, IsString, MaxLength, Validate } from 'class-validator';
+import { IsStringValueRecord } from '../../common/validators/IsStringValueRecord';
 
 /**
- * Body del PUT que renombra a un usuario. El correo es inmutable en el rbac y el grupo se mueve
- * reasignando el rol, así que aquí no viaja ninguno de los dos.
+ * Body del PUT que edita a un usuario: nombre y campos personalizados. `customFields` se fusiona con los
+ * actuales (solo cambian las claves enviadas; "" borra una). Correo y grupo no viajan aquí.
  */
 export class UpdateTenantUserRequest {
     @Expose() @IsOptional() @IsString() @IsNotEmpty() @MaxLength(120) displayName?: string;
+    @Expose()
+    @IsOptional()
+    @IsObject()
+    @Validate(IsStringValueRecord, { message: 'customFields: todos los valores deben ser string' })
+    customFields?: { [key: string]: string };
     @Expose() @IsString() @IsNotEmpty() actedBy!: string;
 }

package/src/retailCatalog/dtos/Product.ts

@@ -51,4 +51,10 @@ export class Product {
     currentPriceSk?: string | null;
     /** Producto físico o servicio; inmutable tras el alta. Ausente = PRODUCT. */
     itemType?: ItemTypeEnum;
+    /** Prioridad de venta 0–100; «Recomendados» ordena por ella. */
+    salePriority?: number;
+    highlights?: string[];
+    warrantyMonths?: number;
+    /** Fecha ISO 8601. */
+    launchDate?: string;
 }

package/src/retailCatalog/dtos/requests/BackofficeCreateProductRequest.ts

@@ -1,4 +1,4 @@
-import { IsArray, IsBoolean, IsEnum, IsIn, IsOptional, IsString, Length, Matches, Validate, ValidateIf } from 'class-validator';
+import { IsArray, IsBoolean, IsEnum, IsIn, IsInt, IsISO8601, IsObject, IsOptional, IsString, Length, Matches, Max, Min, Validate, ValidateIf } from 'class-validator';
 import { SKU_PATTERN } from '../../constants/SkuPattern';
 import { NON_BUNDLE_CATEGORIES } from '../../constants/NonBundleCategories';
 import { ProductCategoryEnum } from '../../enums/ProductCategoryEnum';
@@ -89,4 +89,33 @@ export class BackofficeCreateProductRequest {
     @IsOptional()
     @IsEnum(MdmLockModeEnum)
     mdmLockMode?: MdmLockModeEnum | null;
+
+    /** Prioridad de venta: 100 sale primero en «Recomendados». */
+    @IsOptional()
+    @IsInt()
+    @Min(0)
+    @Max(100)
+    salePriority?: number;
+
+    @IsOptional()
+    @IsArray()
+    @Matches(/\S/, { each: true })
+    @IsString({ each: true })
+    highlights?: string[];
+
+    /** 0 = sin garantía. */
+    @IsOptional()
+    @IsInt()
+    @Min(0)
+    warrantyMonths?: number;
+
+    /** Fecha ISO 8601. */
+    @IsOptional()
+    @IsISO8601()
+    launchDate?: string;
+
+    /** Ficha técnica como mapa clave/valor, igual que Product.specs. */
+    @IsOptional()
+    @IsObject()
+    specs?: Record<string, unknown>;
 }

package/src/retailCatalog/dtos/requests/BackofficeRegisterAdjustmentRequest.ts

@@ -31,4 +31,10 @@ export class BackofficeRegisterAdjustmentRequest {
     @Matches(/^\S+$/, { each: true })
     @IsString({ each: true })
     identifiers?: string[];
+
+    /** movementId del MOV# que este ajuste corrige; el catálogo responde 404 si no existe. */
+    @IsOptional()
+    @Matches(/^\S+$/)
+    @IsString()
+    reversesMovementId?: string;
 }

package/src/retailCatalog/dtos/requests/BackofficeUpdateProductRequest.ts

@@ -1,5 +1,5 @@
 import { Type } from 'class-transformer';
-import { ArrayMinSize, IsArray, IsBoolean, IsEnum, IsIn, IsOptional, IsString, Matches, Validate, ValidateNested } from 'class-validator';
+import { ArrayMinSize, IsArray, IsBoolean, IsEnum, IsIn, IsInt, IsISO8601, IsObject, IsOptional, IsString, Matches, Max, Min, Validate, ValidateNested } from 'class-validator';
 import { NON_BUNDLE_CATEGORIES } from '../../constants/NonBundleCategories';
 import { ProductCategoryEnum } from '../../enums/ProductCategoryEnum';
 import { ProductTierEnum } from '../../enums/ProductTierEnum';
@@ -90,4 +90,33 @@ export class BackofficeUpdateProductRequest {
     @IsOptional()
     @IsEnum(MdmLockModeEnum)
     mdmLockMode?: MdmLockModeEnum | null;
+
+    /** Prioridad de venta: 100 sale primero en «Recomendados». */
+    @IsOptional()
+    @IsInt()
+    @Min(0)
+    @Max(100)
+    salePriority?: number;
+
+    @IsOptional()
+    @IsArray()
+    @Matches(/\S/, { each: true })
+    @IsString({ each: true })
+    highlights?: string[];
+
+    /** 0 = sin garantía. */
+    @IsOptional()
+    @IsInt()
+    @Min(0)
+    warrantyMonths?: number;
+
+    /** Fecha ISO 8601. */
+    @IsOptional()
+    @IsISO8601()
+    launchDate?: string;
+
+    /** Ficha técnica como mapa clave/valor, igual que Product.specs. */
+    @IsOptional()
+    @IsObject()
+    specs?: Record<string, unknown>;
 }

package/src/retailCatalog/dtos/requests/HoldStockRequest.ts

@@ -0,0 +1,28 @@
+import { Type } from 'class-transformer';
+import { ArrayMinSize, IsArray, IsString, ValidateNested } from 'class-validator';
+import { ReservationLineRef } from './ReservationLineRef';
+
+/** Componente de la línea con las piezas que quedan HELD de la sesión. */
+export class HoldStockComponent {
+    @IsString()
+    sku!: string;
+
+    @IsArray()
+    @IsString({ each: true })
+    identifiers!: string[];
+}
+
+/** Body de PUT /private/stores/{storeId}/holds (privateHoldStock); fija las piezas de una línea. */
+export class HoldStockRequest extends ReservationLineRef {
+    @IsString()
+    sessionId!: string;
+
+    @IsString()
+    retailerId!: string;
+
+    @IsArray()
+    @ArrayMinSize(1)
+    @ValidateNested({ each: true })
+    @Type(() => HoldStockComponent)
+    components!: HoldStockComponent[];
+}

package/src/retailCatalog/dtos/requests/ReserveStockRequest.ts

@@ -1,4 +1,5 @@
-import { IsInt, IsString, Min } from 'class-validator';
+import { IsEnum, IsInt, IsOptional, IsString, Min } from 'class-validator';
+import { ReservePurposeEnum } from '../../enums/ReservePurposeEnum';
 
 /** Body de PUT /private/stores/{storeId}/reservations (privateReserveStock); reserva una línea, kit completo. */
 export class ReserveStockRequest {
@@ -21,4 +22,9 @@ export class ReserveStockRequest {
     @IsInt()
     @Min(1)
     qty!: number;
+
+    /** GIFT aparta un regalo de Promociones; ausente = apartado normal de venta. */
+    @IsOptional()
+    @IsEnum(ReservePurposeEnum)
+    purpose?: ReservePurposeEnum;
 }

package/src/retailCatalog/dtos/requests/SuggestPiecesQuery.ts

@@ -1,4 +1,4 @@
-import { IsString, MinLength } from 'class-validator';
+import { IsNotEmpty, IsOptional, IsString, MinLength } from 'class-validator';
 
 /** Query de GET /private/stores/{storeId}/pieces (privateSuggestPieces); sku es el componente si es kit. */
 export class SuggestPiecesQuery {
@@ -8,4 +8,10 @@ export class SuggestPiecesQuery {
     @IsString()
     @MinLength(4)
     prefix!: string;
+
+    /** Sesión que pide; incluye sus propias piezas HELD en las sugerencias. */
+    @IsOptional()
+    @IsString()
+    @IsNotEmpty()
+    sessionId?: string;
 }

package/src/retailCatalog/dtos/responses/GetInventorySkuResponse.ts

@@ -1,5 +1,6 @@
 import type { InventoryItemStatusEnum } from '../../enums/InventoryItemStatusEnum';
 import type { InventoryMovementTypeEnum } from '../../enums/InventoryMovementTypeEnum';
+import type { InventoryMovementReasonEnum } from '../../enums/InventoryMovementReasonEnum';
 import type { SkuPriceEntry } from './SkuPriceEntry';
 
 /** Un movimiento del libro de inventario. */
@@ -12,6 +13,8 @@ export interface InventoryMovementEntry {
     identifier: string | null;
     occurredAt: string;
     createdBy: string;
+    /** Motivo guardado en el MOV#; ausente en los tipos que no llevan motivo. */
+    reason?: InventoryMovementReasonEnum;
 }
 
 /** Pieza de una tienda; status AVAILABLE, SOLD o DAMAGED. */

package/src/retailCatalog/dtos/responses/HoldStockResponse.ts

@@ -0,0 +1,9 @@
+import type { HoldStockComponent } from '../requests/HoldStockRequest';
+
+/** Response de privateHoldStock: la línea con las piezas que quedaron HELD. */
+export interface HoldStockResponse {
+    lineId: string;
+    reservationId: string;
+    sessionId: string;
+    components: HoldStockComponent[];
+}

package/src/retailCatalog/dtos/responses/StoreCatalogItem.ts

@@ -6,6 +6,11 @@ import type { TrackingModeEnum } from '../../enums/TrackingModeEnum';
 import type { ItemTypeEnum } from '../../enums/ItemTypeEnum';
 import type { ProductComponent } from '../ProductComponent';
 
+/** Componente de un kit en el catálogo de venta, con la categoría de su SKU. */
+export interface StoreCatalogComponent extends ProductComponent {
+    category?: ProductCategoryEnum;
+}
+
 /** Fila por SKU del catálogo de venta de una tienda (privateGetStoreStockCatalog). */
 export interface StoreCatalogItem {
     sku: string;
@@ -25,7 +30,7 @@ export interface StoreCatalogItem {
     mdmProvider: MdmProviderEnum | null;
     mdmLockMode: MdmLockModeEnum | null;
     /** Solo si es kit. */
-    components?: ProductComponent[];
+    components?: StoreCatalogComponent[];
     /** Producto físico o servicio. Ausente = PRODUCT. */
     itemType?: ItemTypeEnum;
     /** Nombre visible para kits y servicios, que no tienen marca/modelo. */

package/src/retailCatalog/enums/InventoryInboundMessageTypeEnum.ts

@@ -0,0 +1,5 @@
+/** Tipo de aviso que el wizard publica en la cola de inventario del catálogo. */
+export enum InventoryInboundMessageTypeEnum {
+    SALE_APPLIED = 'SALE_APPLIED',
+    RETURN = 'RETURN',
+}

package/src/retailCatalog/enums/InventoryItemStatusEnum.ts

@@ -1,6 +1,6 @@
 /**
  * Estado de una unidad física (IMEI) en inventario.
- * Transiciones: AVAILABLE → RESERVED → SOLD/AVAILABLE (release); RETURNED desde SOLD; DAMAGED.
+ * Transiciones: AVAILABLE → RESERVED → SOLD/AVAILABLE (release); AVAILABLE → HELD → SOLD/AVAILABLE; RETURNED desde SOLD; DAMAGED.
  * @enum {string}
  *
  * @property {string} AVAILABLE - Disponible en stock.
@@ -9,6 +9,7 @@
  * @property {string} RETURNED - Devuelta por el cliente.
  * @property {string} DAMAGED - Dañada, fuera de stock vendible.
  * @property {string} IN_TRANSIT - En traspaso entre tiendas, fuera de stock vendible.
+ * @property {string} HELD - Capturada por una sesión de venta; no vence hasta venderse o soltarse.
  */
 export enum InventoryItemStatusEnum {
     AVAILABLE = 'AVAILABLE',
@@ -17,4 +18,5 @@ export enum InventoryItemStatusEnum {
     RETURNED = 'RETURNED',
     DAMAGED = 'DAMAGED',
     IN_TRANSIT = 'IN_TRANSIT',
+    HELD = 'HELD',
 }

package/src/retailCatalog/enums/ReservePurposeEnum.ts

@@ -0,0 +1,4 @@
+/** Motivo de un apartado; sin valor es un apartado normal de venta. */
+export enum ReservePurposeEnum {
+    GIFT = 'GIFT',
+}

package/src/retailCatalog/events/InventoryInboundMessage.ts

@@ -0,0 +1,5 @@
+import type { InventoryReturnMessage } from './InventoryReturnMessage';
+import type { InventorySaleAppliedMessage } from './InventorySaleAppliedMessage';
+
+/** Cualquier aviso de la cola de inventario; se discrimina por `type`. */
+export type InventoryInboundMessage = InventorySaleAppliedMessage | InventoryReturnMessage;

package/src/retailCatalog/events/InventoryReturnMessage.ts

@@ -0,0 +1,26 @@
+import { Equals, IsISO8601, IsNotEmpty, IsString } from 'class-validator';
+import { InventoryInboundMessageTypeEnum } from '../enums/InventoryInboundMessageTypeEnum';
+import { ReturnStockRequest } from '../dtos/requests/ReturnStockRequest';
+
+/** Aviso de devolución de una venta de la saga en la cola de inventario. */
+export class InventoryReturnMessage extends ReturnStockRequest {
+    @Equals(InventoryInboundMessageTypeEnum.RETURN)
+    type!: InventoryInboundMessageTypeEnum.RETURN;
+
+    @IsString()
+    @IsNotEmpty()
+    tenantId!: string;
+
+    @IsString()
+    @IsNotEmpty()
+    storeId!: string;
+
+    /** Sesión de la venta; ubica su marcador IDEMP#SELL. */
+    @IsString()
+    @IsNotEmpty()
+    sessionId!: string;
+
+    /** Fecha de la devolución; es el occurredAt del MOV#. */
+    @IsISO8601()
+    returnedAt!: string;
+}

package/src/retailCatalog/events/InventorySaleAppliedMessage.ts

@@ -0,0 +1,26 @@
+import { Equals, IsISO8601, IsNotEmpty, IsString } from 'class-validator';
+import { InventoryInboundMessageTypeEnum } from '../enums/InventoryInboundMessageTypeEnum';
+import { SellStockRequest } from '../dtos/requests/SellStockRequest';
+
+/** Aviso de venta de la saga en la cola de inventario; el catálogo pasa las piezas HELD a SOLD. */
+export class InventorySaleAppliedMessage extends SellStockRequest {
+    @Equals(InventoryInboundMessageTypeEnum.SALE_APPLIED)
+    type!: InventoryInboundMessageTypeEnum.SALE_APPLIED;
+
+    /** La cola es compartida entre silos; el tenant elige las tablas. */
+    @IsString()
+    @IsNotEmpty()
+    tenantId!: string;
+
+    @IsString()
+    @IsNotEmpty()
+    storeId!: string;
+
+    @IsString()
+    @IsNotEmpty()
+    saleId!: string;
+
+    /** Fecha de la venta; fecha el DAY# y el MOV#. */
+    @IsISO8601()
+    soldAt!: string;
+}

package/src/retailCatalog/index.ts

@@ -92,3 +92,12 @@ export * from './dtos/requests/BackofficeCreateTransferRequest';
 export * from './dtos/requests/BackofficeListTransfersQuery';
 export * from './dtos/responses/TransferResponse';
 export * from './dtos/responses/ListTransfersResponse';
+
+// Venta saga (ciclo 3)
+export * from './enums/ReservePurposeEnum';
+export * from './enums/InventoryInboundMessageTypeEnum';
+export * from './dtos/requests/HoldStockRequest';
+export * from './dtos/responses/HoldStockResponse';
+export * from './events/InventorySaleAppliedMessage';
+export * from './events/InventoryReturnMessage';
+export * from './events/InventoryInboundMessage';

package/src/retailPromotions/constants/bonusPreMoney.ts

@@ -0,0 +1,19 @@
+/** HTTP con los que el request no llegó al handler del processor: los contesta la infraestructura. */
+export const PRE_HANDLER_HTTP_STATUSES: ReadonlySet<number> = new Set([401, 403, 404, 405]);
+
+/**
+ * Codes de transaction-processor que prueban que el bono NO movió saldo.
+ * Es whitelist: cualquier otro code se trata como ambiguo (`UNVERIFIED`).
+ */
+export const BONUS_PRE_MONEY_CODES: ReadonlySet<string> = new Set<string>([
+    'USER_NOT_ACTIVE',
+    'ACCOUNT_NOT_FOUND',
+    'ACCOUNT_BLOCKED',
+    'DOCUMENT_ID_NOT_FOUND',
+    'PRODUCT_NOT_FOUND',
+    'ACCOUNT_LEVEL_MAX_MONTHLY_AMOUNT_EXCEEDED',
+    'ACCOUNT_LEVEL_MAX_AVAILABLE_BALANCE_EXCEEDED',
+    'INVALID_REQUEST',
+    // Literal del decorador de idempotencia, no del enum del processor: por eso el Set es de string.
+    'IDEMPOTENCY_KEY_REQUIRED',
+]);

package/src/retailPromotions/constants/retailPromotionsErrorHttpStatus.ts

@@ -0,0 +1,21 @@
+import { RetailPromotionsErrorCodeEnum as C } from '../enums/RetailPromotionsErrorCodeEnum';
+
+/** Status HTTP de cada code: 404 no existe · 409 conflicto de estado · 422 regla de negocio. */
+export const RETAIL_PROMOTIONS_ERROR_HTTP_STATUS: Readonly<Record<C, 404 | 409 | 422>> = {
+    [C.INVALID_PROMOTION_TRANSITION]: 409,
+    [C.CODE_TEXT_TAKEN]: 409,
+    [C.PROMOTION_NOT_ACTIVE]: 409,
+    [C.PROMOTION_NOT_APPLICABLE]: 422,
+    [C.CUSTOMER_NOT_IDENTIFIED]: 422,
+    [C.GIFT_NOT_ALLOWED]: 422,
+    [C.INSUFFICIENT_STOCK]: 409,
+    [C.CODE_NOT_FOUND]: 404,
+    [C.CODE_NOT_APPLICABLE]: 422,
+    [C.CODE_NOT_OWNED]: 422,
+    [C.CODE_NOT_ACTIVE]: 409,
+    [C.CODE_EXHAUSTED]: 409,
+    [C.CODE_ALREADY_APPLIED]: 409,
+    [C.DISCOUNT_AFTER_QUOTE]: 409,
+    [C.INVALID_SALE_PROMOTION]: 422,
+    [C.INVALID_DISCOUNT_CODE]: 422,
+};

package/src/retailPromotions/constants/salePromotionTransitions.ts

@@ -0,0 +1,11 @@
+import { SalePromotionStatusEnum as S } from '../enums/SalePromotionStatusEnum';
+import { SalePromotionTransitionEnum as T } from '../enums/SalePromotionTransitionEnum';
+
+/** Por cada transición: desde qué estados se permite y a cuál lleva. */
+export const SALE_PROMOTION_TRANSITIONS: Readonly<Record<T, { from: readonly S[]; to: S }>> = {
+    [T.PUBLISH]: { from: [S.DRAFT], to: S.ACTIVE },
+    [T.PAUSE]: { from: [S.ACTIVE], to: S.PAUSED },
+    [T.RESUME]: { from: [S.PAUSED], to: S.ACTIVE },
+    [T.EXPIRE]: { from: [S.ACTIVE, S.PAUSED], to: S.EXPIRED },
+    [T.ARCHIVE]: { from: [S.DRAFT, S.ACTIVE, S.PAUSED, S.EXPIRED], to: S.ARCHIVED },
+};

package/src/retailPromotions/dtos/DiscountCode.ts

@@ -0,0 +1,36 @@
+import { CouponScopeEnum } from '../enums/CouponScopeEnum';
+import { CouponStatusEnum } from '../enums/CouponStatusEnum';
+import { DiscountCodeOriginEnum } from '../enums/DiscountCodeOriginEnum';
+import { DiscountCodeStatusEnum } from '../enums/DiscountCodeStatusEnum';
+import { PromotionAppliesToEnum } from '../enums/PromotionAppliesToEnum';
+import { DiscountValue } from './DiscountValue';
+
+/**
+ * Código de descuento de Admin VL o cupón emitido por una venta (según `origin`).
+ * Los campos de cupón (`ownerCustomerId`, `issuedBySaleId`, `couponScope`) son `null` en los de Admin.
+ */
+export interface DiscountCode {
+    codeId: string;
+    codeText: string;
+    origin: DiscountCodeOriginEnum;
+    status: DiscountCodeStatusEnum | CouponStatusEnum;
+    discount: DiscountValue;
+    validFrom: string | null;
+    validUntil: string | null;
+    /** `null` = sin tope de usos. */
+    maxUses: number | null;
+    uses: number;
+    skus: string[] | null;
+    storeIds: string[] | null;
+    announceInStore: boolean;
+    appliesTo: PromotionAppliesToEnum;
+    ownerCustomerId: string | null;
+    issuedBySaleId: string | null;
+    issuingStoreId: string | null;
+    couponScope: CouponScopeEnum | null;
+    redeemedBySaleId: string | null;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+}

package/src/retailPromotions/dtos/DiscountValue.ts

@@ -0,0 +1,8 @@
+import { DiscountTypeEnum } from '../enums/DiscountTypeEnum';
+
+/** Descuento en $ o %: `amountCents` si es `AMOUNT`, `percentBps` (1000 = 10%) si es `PERCENTAGE`. */
+export interface DiscountValue {
+    type: DiscountTypeEnum;
+    amountCents: number | null;
+    percentBps: number | null;
+}

package/src/retailPromotions/dtos/LinePromotionDiscount.ts

@@ -0,0 +1,10 @@
+/** Desglose por línea de la sesión: qué promo o código la tocó y cuánto bajó. */
+export interface LinePromotionDiscount {
+    lineId: string;
+    promotionId: string | null;
+    promotionVersion: number | null;
+    discountCode: string | null;
+    originalPriceCents: number;
+    discountCents: number;
+    finalPriceCents: number;
+}

package/src/retailPromotions/dtos/SalePromotion.ts

@@ -0,0 +1,36 @@
+import { PromotionAppliesToEnum } from '../enums/PromotionAppliesToEnum';
+import { SalePromotionPhaseEnum } from '../enums/SalePromotionPhaseEnum';
+import { SalePromotionStatusEnum } from '../enums/SalePromotionStatusEnum';
+import { SalePromotionLevers, SalePromotionScope, SalePromotionSegmentation } from './SalePromotionLevers';
+
+/** Promo de venta tal como la devuelve el CRUD. Dinero en centavos, fechas ISO. */
+export interface SalePromotion {
+    promotionId: string;
+    retailerId: string;
+    name: string;
+    /** Texto que ve el cliente en el wizard. */
+    customerText: string;
+    levers: SalePromotionLevers;
+    scope: SalePromotionScope;
+    segmentation: SalePromotionSegmentation;
+    appliesTo: PromotionAppliesToEnum;
+    /** `null` = sin tope. */
+    budgetMaxCents: number | null;
+    budgetConsumedCents: number;
+    redemptionCount: number;
+    validFrom: string | null;
+    /** `null` = permanente. */
+    validUntil: string | null;
+    oncePerCustomer: boolean;
+    status: SalePromotionStatusEnum;
+    /** Derivada; `null` cuando el estado no es `ACTIVE`. */
+    phase: SalePromotionPhaseEnum | null;
+    version: number;
+    pausedAt: string | null;
+    pauseReason: string | null;
+    publishedAt: string | null;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+}