@fiado/type-kit 3.464.0 → 3.466.0

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

@@ -17,7 +17,10 @@ import { MdmProviderEnum } from '../../enums/MdmProviderEnum';
 import { ProductTierEnum } from '../../enums/ProductTierEnum';
 import { IsMdmCoherentConstraint } from '../../validators/IsMdmCoherentConstraint';
 
-/** Body de POST /retailers/:retailerId/products — alta de producto (retailerId/status/audit son server-set). */
+/**
+ * Body de POST /retailers/:retailerId/products — alta de producto (retailerId/status/audit son server-set).
+ * @deprecated Modelo viejo por IMEI; usar BackofficeCreateProductRequest. Se conserva porque otras ramas lo importan.
+ */
 export class CreateProductRequest {
     @Matches(SKU_PATTERN, { message: 'sku admite solo [A-Za-z0-9-]' })
     @Length(1, 64)

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

@@ -1,6 +1,9 @@
 import { ArrayNotEmpty, IsArray, IsString } from 'class-validator';
 
-/** Body de POST /retailers/:retailerId/stores/:storeId/inventory — registrar IMEIs nuevos (lote). */
+/**
+ * Body de POST /retailers/:retailerId/stores/:storeId/inventory — registrar IMEIs nuevos (lote).
+ * @deprecated Modelo viejo por IMEI; usar BackofficeRegisterEntryRequest. Se conserva porque otras ramas lo importan.
+ */
 export class RegisterInventoryRequest {
     @IsString()
     productSku!: string;

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

@@ -0,0 +1,48 @@
+import { Expose, Transform } from 'class-transformer';
+import {
+    IsEnum,
+    IsInt,
+    IsString,
+    Length,
+    Matches,
+    MaxLength,
+    Min,
+    Validate,
+    ValidateIf,
+} from 'class-validator';
+import { SKU_PATTERN } from '../../constants/SkuPattern';
+import { ReturnConditionEnum } from '../../enums/ReturnConditionEnum';
+import { IsPieceRefConstraint } from '../../validators/IsPieceRefConstraint';
+
+/** Condición de una pieza devuelta; ausente = GOOD. Un accesorio por cantidad se declara con sku + qty. */
+export class ReturnPieceCondition {
+    @Expose()
+    @Matches(SKU_PATTERN, { message: 'sku admite solo [A-Za-z0-9-]' })
+    @Length(1, 64)
+    @IsString()
+    sku!: string;
+
+    @Expose()
+    @Validate(IsPieceRefConstraint)
+    identifier?: string;
+
+    /** Unidades del SKU por cantidad con esta condición; las no declaradas vuelven GOOD. */
+    @Expose()
+    @ValidateIf((o: ReturnPieceCondition) => o.qty !== undefined)
+    @IsInt()
+    @Min(1)
+    qty?: number;
+
+    @Expose()
+    @Transform(({ value }) => value ?? ReturnConditionEnum.GOOD)
+    @IsEnum(ReturnConditionEnum)
+    condition: ReturnConditionEnum = ReturnConditionEnum.GOOD;
+
+    /** Motivo del daño; obligatorio con DAMAGED, opcional con GOOD. */
+    @Expose()
+    @ValidateIf((o: ReturnPieceCondition) => o.condition === ReturnConditionEnum.DAMAGED || o.reason != null)
+    @MaxLength(200)
+    @Matches(/\S/)
+    @IsString()
+    reason?: string;
+}

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

@@ -0,0 +1,13 @@
+import { Type } from 'class-transformer';
+import { IsArray, IsOptional, ValidateNested } from 'class-validator';
+import { ReturnPieceCondition } from './ReturnPieceCondition';
+import { StockLine } from './StockLine';
+
+/** Línea de devolución: la línea vendida más la condición de sus piezas; las no listadas vuelven GOOD. */
+export class ReturnStockLine extends StockLine {
+    @IsOptional()
+    @IsArray()
+    @ValidateNested({ each: true })
+    @Type(() => ReturnPieceCondition)
+    conditions?: ReturnPieceCondition[];
+}

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

@@ -1,6 +1,6 @@
 import { Type } from 'class-transformer';
 import { ArrayMinSize, IsArray, IsISO8601, IsString, ValidateNested } from 'class-validator';
-import { StockLine } from './StockLine';
+import { ReturnStockLine } from './ReturnStockLine';
 
 /** Body de PUT /private/stores/{storeId}/returns (privateReturnStock); componentes guardados en la venta. */
 export class ReturnStockRequest {
@@ -17,6 +17,6 @@ export class ReturnStockRequest {
     @IsArray()
     @ArrayMinSize(1)
     @ValidateNested({ each: true })
-    @Type(() => StockLine)
-    lines!: StockLine[];
+    @Type(() => ReturnStockLine)
+    lines!: ReturnStockLine[];
 }

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

@@ -1,6 +1,9 @@
 import { IsString } from 'class-validator';
 
-/** Body de PUT /retailers/:retailerId/inventory/:imei/transfer — mover IMEI a otro store. */
+/**
+ * Body de PUT /retailers/:retailerId/inventory/:imei/transfer — mover IMEI a otro store.
+ * @deprecated Modelo viejo por IMEI; usar BackofficeCreateTransferRequest. Se conserva porque otras ramas lo importan.
+ */
 export class TransferInventoryRequest {
     @IsString()
     newStoreId!: string;

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

@@ -14,7 +14,10 @@ import { MdmProviderEnum } from '../../enums/MdmProviderEnum';
 import { ProductTierEnum } from '../../enums/ProductTierEnum';
 import { IsMdmCoherentConstraint } from '../../validators/IsMdmCoherentConstraint';
 
-/** Body de PUT /retailers/:retailerId/products/:sku — actualización parcial (sku y status son inmutables acá). */
+/**
+ * Body de PUT /retailers/:retailerId/products/:sku — actualización parcial (sku y status son inmutables acá).
+ * @deprecated Modelo viejo por IMEI; usar BackofficeUpdateProductRequest. Se conserva porque otras ramas lo importan.
+ */
 export class UpdateProductRequest {
     @IsOptional()
     @IsString()

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

@@ -1,7 +1,10 @@
 import { IsEnum } from 'class-validator';
 import { ProductStatusEnum } from '../../enums/ProductStatusEnum';
 
-/** Body de PUT /retailers/:retailerId/products/:sku/status — ACTIVE | DISCONTINUED. */
+/**
+ * Body de PUT /retailers/:retailerId/products/:sku/status — ACTIVE | DISCONTINUED.
+ * @deprecated Modelo viejo por IMEI; usar backofficeDeactivateProduct (sin body). Se conserva porque otras ramas lo importan.
+ */
 export class UpdateProductStatusRequest {
     @IsEnum(ProductStatusEnum)
     status!: ProductStatusEnum;

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

@@ -4,6 +4,7 @@ import type { ProductCategoryEnum } from '../../enums/ProductCategoryEnum';
 import type { ProductTierEnum } from '../../enums/ProductTierEnum';
 import type { InventoryLensUnavailableReasonEnum } from '../../enums/InventoryLensUnavailableReasonEnum';
 import type { InventoryTransferReasonEnum } from '../../enums/InventoryTransferReasonEnum';
+import type { ItemTypeEnum } from '../../enums/ItemTypeEnum';
 
 /**
  * Los contadores que la pantalla «Inventario» del Admin VL pinta arriba, siempre — los cuatro viajan
@@ -127,6 +128,8 @@ export interface InventoryLensListItem {
     coverage: InventoryLensCoverage;
     alerts: InventoryLensAlerts;
     sold30d: number;
+    /** Producto físico o servicio. Ausente = PRODUCT. */
+    itemType?: ItemTypeEnum;
 }
 
 /** Fila del lente — el tipo depende del tab pedido. */

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

@@ -0,0 +1,6 @@
+import type { TransferResponse } from './TransferResponse';
+
+/** Response de backofficeListTransfers. */
+export interface ListTransfersResponse {
+    items: TransferResponse[];
+}

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

@@ -8,6 +8,8 @@ export interface ReservedComponent {
     qty: number;
     category: ProductCategoryEnum;
     trackingMode: TrackingModeEnum;
+    /** Precio vigente del componente, para repartir el precio del kit. */
+    priceCents?: number;
 }
 
 /** Response de privateReserveStock; el precio de la línea es `basePriceCents`. */

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

@@ -5,6 +5,8 @@ export interface SkuPriceEntry {
     effectiveFrom: string;
     listPriceCents: number | null;
     basePriceCents: number;
+    /** Precio del SKU dentro de un kit; informativo, no se aplica. */
+    comboPriceCents?: number;
     source: PriceSourceEnum;
     createdBy: string;
 }

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

@@ -3,6 +3,7 @@ import type { MdmProviderEnum } from '../../enums/MdmProviderEnum';
 import type { ProductCategoryEnum } from '../../enums/ProductCategoryEnum';
 import type { ProductTierEnum } from '../../enums/ProductTierEnum';
 import type { TrackingModeEnum } from '../../enums/TrackingModeEnum';
+import type { ItemTypeEnum } from '../../enums/ItemTypeEnum';
 import type { ProductComponent } from '../ProductComponent';
 
 /** Fila por SKU del catálogo de venta de una tienda (privateGetStoreStockCatalog). */
@@ -25,6 +26,8 @@ export interface StoreCatalogItem {
     mdmLockMode: MdmLockModeEnum | null;
     /** Solo si es kit. */
     components?: ProductComponent[];
+    /** Producto físico o servicio. Ausente = PRODUCT. */
+    itemType?: ItemTypeEnum;
 }
 
 /** Response de privateGetStoreStockCatalog. */

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

@@ -0,0 +1,17 @@
+import type { TransferStateEnum } from '../../enums/TransferStateEnum';
+
+/** Un traspaso entre tiendas (TRF#); response de crear, recibir y cancelar. */
+export interface TransferResponse {
+    transferId: string;
+    fromStoreId: string;
+    toStoreId: string;
+    sku: string;
+    qty: number;
+    /** IMEI o serie de cada pieza; vacío si el SKU se rastrea por cantidad. */
+    identifiers: string[];
+    state: TransferStateEnum;
+    createdBy: string;
+    updatedBy: string;
+    createdAt: string;
+    updatedAt: string;
+}

package/src/retailCatalog/enums/InventoryItemStatusEnum.ts

@@ -8,6 +8,7 @@
  * @property {string} SOLD - Vendida.
  * @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.
  */
 export enum InventoryItemStatusEnum {
     AVAILABLE = 'AVAILABLE',
@@ -15,4 +16,5 @@ export enum InventoryItemStatusEnum {
     SOLD = 'SOLD',
     RETURNED = 'RETURNED',
     DAMAGED = 'DAMAGED',
+    IN_TRANSIT = 'IN_TRANSIT',
 }

package/src/retailCatalog/enums/InventoryMovementReasonEnum.ts

@@ -0,0 +1,7 @@
+/** Motivo de un movimiento manual de inventario (MOV#): merma, ajuste, garantía o devolución dañada. */
+export enum InventoryMovementReasonEnum {
+    SHRINKAGE = 'SHRINKAGE',
+    ADJUSTMENT = 'ADJUSTMENT',
+    WARRANTY = 'WARRANTY',
+    DAMAGED_RETURN = 'DAMAGED_RETURN',
+}

package/src/retailCatalog/enums/InventoryMovementTypeEnum.ts

@@ -6,4 +6,7 @@ export enum InventoryMovementTypeEnum {
     SALE = 'SALE',
     RETURN = 'RETURN',
     ADJUSTMENT = 'ADJUSTMENT',
+    TRANSFER_OUT = 'TRANSFER_OUT',
+    TRANSFER_IN = 'TRANSFER_IN',
+    TRANSFER_CANCEL = 'TRANSFER_CANCEL',
 }

package/src/retailCatalog/enums/ItemTypeEnum.ts

@@ -0,0 +1,5 @@
+/** Tipo de ítem del catálogo: producto físico o servicio sin stock. Inmutable tras el alta. */
+export enum ItemTypeEnum {
+    PRODUCT = 'PRODUCT',
+    SERVICE = 'SERVICE',
+}

package/src/retailCatalog/enums/PriceSourceEnum.ts

@@ -1,4 +1,5 @@
-/** Origen de un registro del historial de precios (PRICE#). */
+/** Origen de un registro de catálogo (PRODUCT#, PRICE#, MOV#): la puerta de Zentral o el backoffice. */
 export enum PriceSourceEnum {
     ZENTRAL_SYNC = 'ZENTRAL_SYNC',
+    BACKOFFICE = 'BACKOFFICE',
 }

package/src/retailCatalog/enums/ReturnConditionEnum.ts

@@ -0,0 +1,5 @@
+/** Condición de una pieza devuelta; DAMAGED no regresa al disponible. */
+export enum ReturnConditionEnum {
+    GOOD = 'GOOD',
+    DAMAGED = 'DAMAGED',
+}

package/src/retailCatalog/enums/TransferStateEnum.ts

@@ -0,0 +1,6 @@
+/** Estado de un traspaso entre tiendas (TRF#); solo uno OPEN se recibe o cancela. */
+export enum TransferStateEnum {
+    OPEN = 'OPEN',
+    RECEIVED = 'RECEIVED',
+    CANCELLED = 'CANCELLED',
+}

package/src/retailCatalog/index.ts

@@ -11,9 +11,12 @@ export * from './enums/InventoryTransferReasonEnum';
 
 // Constantes del dominio
 export * from './constants/SkuPattern';
+export * from './constants/NonBundleCategories';
+export * from './constants/AdjustmentReasons';
 
 // Validators custom
 export * from './validators/IsMdmCoherentConstraint';
+export * from './validators/IsPieceRefConstraint';
 
 // Entity DTOs
 export * from './dtos/Product';
@@ -51,6 +54,8 @@ export * from './enums/InventoryLensPeriodEnum';
 export * from './dtos/ProductComponent';
 export * from './dtos/requests/ReservationLineRef';
 export * from './dtos/requests/StockLine';
+export * from './dtos/requests/ReturnPieceCondition';
+export * from './dtos/requests/ReturnStockLine';
 export * from './dtos/requests/ReserveStockRequest';
 export * from './dtos/requests/RenewReservationsRequest';
 export * from './dtos/requests/SuggestPiecesQuery';
@@ -70,3 +75,20 @@ export * from './dtos/responses/StoreCatalogItem';
 export * from './dtos/responses/SkuPriceEntry';
 export * from './dtos/responses/GetInventorySkuResponse';
 export * from './dtos/responses/ListSkuPricesResponse';
+
+// Operación independiente (ciclo 2)
+export * from './enums/ItemTypeEnum';
+export * from './enums/ReturnConditionEnum';
+export * from './enums/TransferStateEnum';
+export * from './enums/InventoryMovementReasonEnum';
+export * from './dtos/requests/BackofficeCreateProductRequest';
+export * from './dtos/requests/BackofficeCreateKitRequest';
+export * from './dtos/requests/BackofficeCreateServiceRequest';
+export * from './dtos/requests/BackofficeUpdateProductRequest';
+export * from './dtos/requests/BackofficeCreateSkuPriceRequest';
+export * from './dtos/requests/BackofficeRegisterEntryRequest';
+export * from './dtos/requests/BackofficeRegisterAdjustmentRequest';
+export * from './dtos/requests/BackofficeCreateTransferRequest';
+export * from './dtos/requests/BackofficeListTransfersQuery';
+export * from './dtos/responses/TransferResponse';
+export * from './dtos/responses/ListTransfersResponse';

package/src/retailCatalog/validators/IsPieceRefConstraint.ts

@@ -0,0 +1,19 @@
+import {
+    ValidatorConstraint,
+    type ValidationArguments,
+    type ValidatorConstraintInterface,
+} from 'class-validator';
+
+/** Exige identifier (pieza con IMEI o serie) o qty (SKU por cantidad), nunca los dos. */
+@ValidatorConstraint({ name: 'isPieceRef', async: false })
+export class IsPieceRefConstraint implements ValidatorConstraintInterface {
+    validate(identifier: unknown, args: ValidationArguments): boolean {
+        const { qty } = args.object as { qty?: unknown };
+        if (qty !== undefined) return identifier === undefined;
+        return typeof identifier === 'string' && /^\S+$/.test(identifier);
+    }
+
+    defaultMessage(): string {
+        return 'identifier (pieza con IMEI o serie) o qty (por cantidad), exactamente uno';
+    }
+}

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

@@ -1,5 +1,6 @@
-import { Expose } from 'class-transformer';
-import { IsBoolean, IsOptional, IsString, MaxLength, MinLength } from 'class-validator';
+import { Expose, Type } from 'class-transformer';
+import { IsArray, IsBoolean, IsOptional, IsString, MaxLength, MinLength, ValidateNested } from 'class-validator';
+import { ReturnPieceCondition } from '../../../retailCatalog/dtos/requests/ReturnPieceCondition';
 
 /**
  * POST /backoffice/sales/:saleId/cancel — cancelación del Admin VL. SureKeep Fase 3 — pista Retail.
@@ -39,4 +40,12 @@ export class BackofficeCancelSaleRequest {
     @IsString()
     @MaxLength(64)
     outOfWindowExceptionId?: string;
+
+    /** Condición de cada pieza que regresa al inventario; las no listadas vuelven GOOD. */
+    @Expose()
+    @IsOptional()
+    @IsArray()
+    @ValidateNested({ each: true })
+    @Type(() => ReturnPieceCondition)
+    returnConditions?: ReturnPieceCondition[];
 }

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

@@ -1,5 +1,6 @@
-import { Expose } from 'class-transformer';
-import { IsBoolean, IsOptional, IsString, MaxLength } from 'class-validator';
+import { Expose, Type } from 'class-transformer';
+import { IsArray, IsBoolean, IsOptional, IsString, MaxLength, ValidateNested } from 'class-validator';
+import { ReturnPieceCondition } from '../../../retailCatalog/dtos/requests/ReturnPieceCondition';
 
 /**
  * POST /sales/:saleId/cancel — cancela una venta (flujo C, solo BO dentro de ventana param). `reason`
@@ -29,4 +30,12 @@ export class CancelSaleRequest {
   @IsOptional()
   @IsBoolean()
   equipmentVerified?: boolean;
+
+  /** Condición de cada pieza que regresa al inventario; las no listadas vuelven GOOD. */
+  @Expose()
+  @IsOptional()
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => ReturnPieceCondition)
+  returnConditions?: ReturnPieceCondition[];
 }