@fiado/type-kit 3.472.0 → 3.474.0

package/bin/retailWizard/events/RetailPromotionInboundMessage.js

@@ -0,0 +1,162 @@
+"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.RetailPromotionInboundMessage = exports.RetailPromotionInboundLine = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const RetailPromotionInboundMessageTypeEnum_1 = require("../enums/RetailPromotionInboundMessageTypeEnum");
+const WizardLineRoleEnum_1 = require("../enums/WizardLineRoleEnum");
+/** Línea de la venta en el mensaje de Promociones. */
+class RetailPromotionInboundLine {
+}
+exports.RetailPromotionInboundLine = RetailPromotionInboundLine;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundLine.prototype, "lineId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundLine.prototype, "sku", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], RetailPromotionInboundLine.prototype, "qty", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(WizardLineRoleEnum_1.WizardLineRoleEnum),
+    __metadata("design:type", String)
+], RetailPromotionInboundLine.prototype, "role", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundLine.prototype, "linkedLineId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundLine.prototype, "promotionId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], RetailPromotionInboundLine.prototype, "promotionVersion", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundLine.prototype, "discountCode", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], RetailPromotionInboundLine.prototype, "discountCents", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], RetailPromotionInboundLine.prototype, "originalPriceCents", void 0);
+__decorate([
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.IsString)({ each: true }),
+    __metadata("design:type", Array)
+], RetailPromotionInboundLine.prototype, "identifiers", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], RetailPromotionInboundLine.prototype, "returned", void 0);
+/** Venta confirmada o cancelada que el wizard publica en RetailPromotionInboundQueue; crédito = trae creditId. */
+class RetailPromotionInboundMessage {
+}
+exports.RetailPromotionInboundMessage = RetailPromotionInboundMessage;
+__decorate([
+    (0, class_validator_1.IsEnum)(RetailPromotionInboundMessageTypeEnum_1.RetailPromotionInboundMessageTypeEnum),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "type", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "tenantId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "retailerId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "storeId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "saleId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "sessionId", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "customerId", void 0);
+__decorate([
+    (0, class_validator_1.IsISO8601)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "soldAt", void 0);
+__decorate([
+    (0, class_validator_1.IsISO8601)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "occurredAt", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "creditId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "fiadoDirectoryId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], RetailPromotionInboundMessage.prototype, "salePromotionId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], RetailPromotionInboundMessage.prototype, "salePromotionVersion", void 0);
+__decorate([
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ArrayMinSize)(1),
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => RetailPromotionInboundLine),
+    __metadata("design:type", Array)
+], RetailPromotionInboundMessage.prototype, "lines", void 0);

package/bin/retailWizard/events/SaleCompletedV1.d.ts

@@ -13,9 +13,8 @@ export interface SaleCompletedV1 {
     sku: string;
     imei: string | null;
     /**
-     * Lo COBRADO en caja al cerrar (contrato histórico — La Central y comisión F4 lo asumen así).
-     * En contado == precio del equipo; en CREDIT es SOLO el enganche: desambiguar con `type` +
-     * `equipmentPriceCents`, NUNCA redefinir este campo.
+     * Lo cobrado en caja al cerrar: enganche + lo no financiado (en contado, el total).
+     * Desambiguar con `type` + `equipmentPriceCents`.
      */
     amountCents: number;
     /**

package/bin/retailWizard/index.d.ts

@@ -23,6 +23,7 @@ export * from './enums/BlockedReasonEnum';
 export * from './enums/BlockedCategoryEnum';
 export * from './enums/WizardLineStatusEnum';
 export * from './enums/LinePaymentTypeEnum';
+export * from './enums/WizardLineRoleEnum';
 export * from './dtos/WizardConsents';
 export * from './dtos/WizardPayment';
 export * from './dtos/WizardProduct';
@@ -38,7 +39,10 @@ export * from './dtos/WizardResumeTarget';
 export * from './dtos/WizardBlocked';
 export * from './dtos/WizardLineProduct';
 export * from './dtos/WizardLineIdentifiers';
+export * from './dtos/WizardLinePromotionFields';
+export * from './dtos/WizardFinancingPreview';
 export * from './dtos/WizardReservedLine';
+export * from './dtos/WizardGiftLine';
 export * from './dtos/SaleLine';
 export * from './dtos/WizardSession';
 export * from './dtos/OtpVerification';
@@ -57,6 +61,10 @@ export * from './dtos/requests/KycManualRequest';
 export * from './dtos/requests/ProofOfAddressPrepareRequest';
 export * from './dtos/requests/OccupationRequest';
 export * from './dtos/requests/AddProductRequest';
+export * from './dtos/requests/PinSessionPiecesRequest';
+export * from './dtos/requests/ApplyLinePromotionRequest';
+export * from './dtos/requests/SetAnchorGiftsRequest';
+export * from './dtos/requests/ApplySalePromotionRequest';
 export * from './dtos/requests/DeleteProductRequest';
 export * from './dtos/requests/SetPaymentMethodRequest';
 export * from './dtos/requests/ExternalReferralRequest';
@@ -129,6 +137,11 @@ export * from './events/SaleCancelledV1';
 export * from './events/SaleCompletedV2';
 export * from './events/SaleCancelledV2';
 export * from './events/SessionExpiredV1';
+export * from './enums/RetailPromotionInboundMessageTypeEnum';
+export * from './events/RetailPromotionInboundMessage';
+export * from './events/RetailCommissionInboundMessage';
 export * from './enums/WizardSessionLookupStatusEnum';
 export * from './dtos/WizardSessionLookupEntry';
 export * from './dtos/responses/WizardSessionLookupResponse';
+export * from './dtos/responses/PrivateWizardSessionResponse';
+export * from './dtos/responses/SetAnchorGiftsResponse';

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

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/retailCatalog/dtos/Product.ts

@@ -3,6 +3,7 @@ import { MdmProviderEnum } from '../enums/MdmProviderEnum';
 import { ProductStatusEnum } from '../enums/ProductStatusEnum';
 import { ProductTierEnum } from '../enums/ProductTierEnum';
 import { ProductCategoryEnum } from '../enums/ProductCategoryEnum';
+import { AccessorySubcategoryEnum } from '../enums/AccessorySubcategoryEnum';
 import { TrackingModeEnum } from '../enums/TrackingModeEnum';
 import { ItemTypeEnum } from '../enums/ItemTypeEnum';
 import { ProductComponent } from './ProductComponent';
@@ -40,6 +41,8 @@ export class Product {
 
     // Campos del inventario multi-item; opcionales hasta que todo producto pase por la puerta de entrada.
     category?: ProductCategoryEnum;
+    /** Solo en ACCESSORY. */
+    accessorySubcategory?: AccessorySubcategoryEnum;
     trackingMode?: TrackingModeEnum;
     /** Se puede vender suelto (fuera de un kit). */
     sellable?: boolean;
@@ -51,4 +54,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,7 +1,8 @@
-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';
+import { AccessorySubcategoryEnum } from '../../enums/AccessorySubcategoryEnum';
 import { ProductTierEnum } from '../../enums/ProductTierEnum';
 import { TrackingModeEnum } from '../../enums/TrackingModeEnum';
 import { MdmLockModeEnum } from '../../enums/MdmLockModeEnum';
@@ -19,6 +20,11 @@ export class BackofficeCreateProductRequest {
     @IsIn(NON_BUNDLE_CATEGORIES)
     category!: ProductCategoryEnum;
 
+    /** Solo en ACCESSORY. */
+    @IsOptional()
+    @IsEnum(AccessorySubcategoryEnum)
+    accessorySubcategory?: AccessorySubcategoryEnum;
+
     /** Inmutable tras el alta. */
     @IsEnum(TrackingModeEnum)
     trackingMode!: TrackingModeEnum;
@@ -89,4 +95,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,7 +1,8 @@
 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 { AccessorySubcategoryEnum } from '../../enums/AccessorySubcategoryEnum';
 import { ProductTierEnum } from '../../enums/ProductTierEnum';
 import { ProductComponent } from '../ProductComponent';
 import { MdmLockModeEnum } from '../../enums/MdmLockModeEnum';
@@ -14,6 +15,11 @@ export class BackofficeUpdateProductRequest {
     @IsIn(NON_BUNDLE_CATEGORIES)
     category?: ProductCategoryEnum;
 
+    /** Solo en ACCESSORY. */
+    @IsOptional()
+    @IsEnum(AccessorySubcategoryEnum)
+    accessorySubcategory?: AccessorySubcategoryEnum;
+
     @IsOptional()
     @IsBoolean()
     sellable?: boolean;
@@ -90,4 +96,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,31 @@
+import { Type } from 'class-transformer';
+import { ArrayMinSize, IsArray, IsNotEmpty, 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()
+    @IsNotEmpty()
+    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()
+    @IsNotEmpty()
+    sessionId!: string;
+
+    @IsString()
+    @IsNotEmpty()
+    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

@@ -1,11 +1,17 @@
 import type { MdmLockModeEnum } from '../../enums/MdmLockModeEnum';
 import type { MdmProviderEnum } from '../../enums/MdmProviderEnum';
 import type { ProductCategoryEnum } from '../../enums/ProductCategoryEnum';
+import type { AccessorySubcategoryEnum } from '../../enums/AccessorySubcategoryEnum';
 import type { ProductTierEnum } from '../../enums/ProductTierEnum';
 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;
@@ -13,6 +19,8 @@ export interface StoreCatalogItem {
     available: number;
     basePriceCents: number;
     category: ProductCategoryEnum;
+    /** Solo en ACCESSORY. */
+    accessorySubcategory?: AccessorySubcategoryEnum;
     trackingMode: TrackingModeEnum;
     brand: string;
     model: string;
@@ -25,7 +33,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/AccessorySubcategoryEnum.ts

@@ -0,0 +1,9 @@
+/** Subcategoría de un producto ACCESSORY; sirve para regalar «por gama» en Promociones. */
+export enum AccessorySubcategoryEnum {
+    AUDIO = 'AUDIO',
+    CHARGING = 'CHARGING',
+    PROTECTION = 'PROTECTION',
+    CABLES = 'CABLES',
+    WEARABLES = 'WEARABLES',
+    OTHER = 'OTHER',
+}

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;
+}