@fiado/type-kit 3.189.0 → 3.191.0

package/src/retailCatalog/dtos/Product.ts

@@ -0,0 +1,35 @@
+import { MdmLockModeEnum } from '../enums/MdmLockModeEnum';
+import { MdmProviderEnum } from '../enums/MdmProviderEnum';
+import { ProductStatusEnum } from '../enums/ProductStatusEnum';
+import { ProductTierEnum } from '../enums/ProductTierEnum';
+
+/**
+ * Product — aggregate root del catálogo del dominio `retailCatalog`
+ * (lambda retail-catalog-business, SureKeep Fase 1 — pista Retail).
+ * Representación de salida/datos: sin decoradores class-validator.
+ */
+export class Product {
+    productId!: string;
+    retailerId!: string;
+    sku!: string;
+    externalId!: string | null;
+    brand!: string;
+    model!: string;
+    capacity!: string;
+    color!: string;
+    description!: string;
+    specs!: Record<string, unknown> | null;
+    imageUrl!: string | null;
+    tier!: ProductTierEnum;
+    basePriceCents!: number;
+    listPriceCents!: number | null;
+    eligibleFinanciers!: string[];
+    mdmEnabled!: boolean;
+    mdmProvider!: MdmProviderEnum | null;
+    mdmLockMode!: MdmLockModeEnum | null;
+    status!: ProductStatusEnum;
+    createdBy!: string;
+    updatedBy!: string;
+    createdAt!: string;
+    updatedAt!: string;
+}

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

@@ -0,0 +1,11 @@
+import { IsIn } from 'class-validator';
+import { InventoryItemStatusEnum } from '../../enums/InventoryItemStatusEnum';
+
+/**
+ * Body de PUT /retailers/:retailerId/inventory/:imei/status — cambio manual de estado.
+ * Acotado a RETURNED | DAMAGED (los otros estados los mueve la máquina de venta, no el operador).
+ */
+export class ChangeInventoryStatusRequest {
+    @IsIn([InventoryItemStatusEnum.RETURNED, InventoryItemStatusEnum.DAMAGED])
+    status!: InventoryItemStatusEnum.RETURNED | InventoryItemStatusEnum.DAMAGED;
+}

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

@@ -0,0 +1,81 @@
+import {
+    IsArray,
+    IsBoolean,
+    IsEnum,
+    IsInt,
+    IsObject,
+    IsOptional,
+    IsString,
+    Length,
+    Matches,
+    Min,
+    Validate,
+} from 'class-validator';
+import { SKU_PATTERN } from '../../constants/SkuPattern';
+import { MdmLockModeEnum } from '../../enums/MdmLockModeEnum';
+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). */
+export class CreateProductRequest {
+    @Matches(SKU_PATTERN, { message: 'sku admite solo [A-Za-z0-9-]' })
+    @Length(1, 64)
+    @IsString()
+    sku!: string;
+
+    @IsOptional()
+    @IsString()
+    externalId?: string | null;
+
+    @IsString()
+    brand!: string;
+
+    @IsString()
+    model!: string;
+
+    @IsString()
+    capacity!: string;
+
+    @IsString()
+    color!: string;
+
+    @IsString()
+    description!: string;
+
+    @IsOptional()
+    @IsObject()
+    specs?: Record<string, unknown> | null;
+
+    @IsOptional()
+    @IsString()
+    imageUrl?: string | null;
+
+    @IsEnum(ProductTierEnum)
+    tier!: ProductTierEnum;
+
+    @IsInt()
+    @Min(0)
+    basePriceCents!: number;
+
+    @IsOptional()
+    @IsInt()
+    @Min(0)
+    listPriceCents?: number | null;
+
+    @IsArray()
+    @IsString({ each: true })
+    eligibleFinanciers!: string[];
+
+    @Validate(IsMdmCoherentConstraint)
+    @IsBoolean()
+    mdmEnabled!: boolean;
+
+    @IsOptional()
+    @IsEnum(MdmProviderEnum)
+    mdmProvider?: MdmProviderEnum | null;
+
+    @IsOptional()
+    @IsEnum(MdmLockModeEnum)
+    mdmLockMode?: MdmLockModeEnum | null;
+}

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

@@ -0,0 +1,22 @@
+import { IsEnum, IsOptional, IsString } from 'class-validator';
+import { ProductStatusEnum } from '../../enums/ProductStatusEnum';
+import { ProductTierEnum } from '../../enums/ProductTierEnum';
+
+/** Query string de GET /retailers/:retailerId/products — filtros opcionales. */
+export class ListProductsQuery {
+    @IsOptional()
+    @IsString()
+    brand?: string;
+
+    @IsOptional()
+    @IsString()
+    model?: string;
+
+    @IsOptional()
+    @IsEnum(ProductTierEnum)
+    tier?: ProductTierEnum;
+
+    @IsOptional()
+    @IsEnum(ProductStatusEnum)
+    status?: ProductStatusEnum;
+}

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

@@ -0,0 +1,12 @@
+import { ArrayNotEmpty, IsArray, IsString } from 'class-validator';
+
+/** Body de POST /retailers/:retailerId/stores/:storeId/inventory — registrar IMEIs nuevos (lote). */
+export class RegisterInventoryRequest {
+    @IsString()
+    productSku!: string;
+
+    @IsArray()
+    @ArrayNotEmpty()
+    @IsString({ each: true })
+    imeis!: string[];
+}

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

@@ -0,0 +1,7 @@
+import { IsString } from 'class-validator';
+
+/** Body de PUT /retailers/:retailerId/inventory/:imei/transfer — mover IMEI a otro store. */
+export class TransferInventoryRequest {
+    @IsString()
+    newStoreId!: string;
+}

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

@@ -0,0 +1,82 @@
+import {
+    IsArray,
+    IsBoolean,
+    IsEnum,
+    IsInt,
+    IsObject,
+    IsOptional,
+    IsString,
+    Min,
+    Validate,
+} from 'class-validator';
+import { MdmLockModeEnum } from '../../enums/MdmLockModeEnum';
+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á). */
+export class UpdateProductRequest {
+    @IsOptional()
+    @IsString()
+    externalId?: string | null;
+
+    @IsOptional()
+    @IsString()
+    brand?: string;
+
+    @IsOptional()
+    @IsString()
+    model?: string;
+
+    @IsOptional()
+    @IsString()
+    capacity?: string;
+
+    @IsOptional()
+    @IsString()
+    color?: string;
+
+    @IsOptional()
+    @IsString()
+    description?: string;
+
+    @IsOptional()
+    @IsObject()
+    specs?: Record<string, unknown> | null;
+
+    @IsOptional()
+    @IsString()
+    imageUrl?: string | null;
+
+    @IsOptional()
+    @IsEnum(ProductTierEnum)
+    tier?: ProductTierEnum;
+
+    @IsOptional()
+    @IsInt()
+    @Min(0)
+    basePriceCents?: number;
+
+    @IsOptional()
+    @IsInt()
+    @Min(0)
+    listPriceCents?: number | null;
+
+    @IsOptional()
+    @IsArray()
+    @IsString({ each: true })
+    eligibleFinanciers?: string[];
+
+    @Validate(IsMdmCoherentConstraint)
+    @IsOptional()
+    @IsBoolean()
+    mdmEnabled?: boolean;
+
+    @IsOptional()
+    @IsEnum(MdmProviderEnum)
+    mdmProvider?: MdmProviderEnum | null;
+
+    @IsOptional()
+    @IsEnum(MdmLockModeEnum)
+    mdmLockMode?: MdmLockModeEnum | null;
+}

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

@@ -0,0 +1,8 @@
+import { IsEnum } from 'class-validator';
+import { ProductStatusEnum } from '../../enums/ProductStatusEnum';
+
+/** Body de PUT /retailers/:retailerId/products/:sku/status — ACTIVE | DISCONTINUED. */
+export class UpdateProductStatusRequest {
+    @IsEnum(ProductStatusEnum)
+    status!: ProductStatusEnum;
+}

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

@@ -0,0 +1,5 @@
+/** Detalle de una fila rechazada en la carga CSV de productos. */
+export class ImportCsvFailure {
+    fila!: number;
+    motivo!: string;
+}

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

@@ -0,0 +1,7 @@
+import { ImportCsvFailure } from './ImportCsvFailure';
+
+/** Response de POST /retailers/:retailerId/products/import-csv — resultado de la carga masiva. */
+export class ImportCsvResult {
+    committed!: string[];
+    failed!: ImportCsvFailure[];
+}

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

@@ -0,0 +1,4 @@
+import { InventoryItem } from '../InventoryItem';
+
+/** Response de los endpoints de inventario (= entidad InventoryItem). */
+export type InventoryItemResponse = InventoryItem;

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

@@ -0,0 +1,4 @@
+import { Product } from '../Product';
+
+/** Response de los endpoints de producto (= entidad Product). */
+export type ProductResponse = Product;

package/src/retailCatalog/dtos/validation/ValidateInventoryResponse.ts

@@ -0,0 +1,12 @@
+import { InventoryItemStatusEnum } from '../../enums/InventoryItemStatusEnum';
+
+/**
+ * Response de GET /private/inventory/:imei — validar IMEI + status + store + producto.
+ * Shape de salida → sin class-validator.
+ */
+export class ValidateInventoryResponse {
+    imei!: string;
+    status!: InventoryItemStatusEnum;
+    storeId!: string;
+    productId!: string;
+}

package/src/retailCatalog/dtos/validation/ValidateProductResponse.ts

@@ -0,0 +1,21 @@
+import { MdmLockModeEnum } from '../../enums/MdmLockModeEnum';
+import { MdmProviderEnum } from '../../enums/MdmProviderEnum';
+import { ProductStatusEnum } from '../../enums/ProductStatusEnum';
+import { ProductTierEnum } from '../../enums/ProductTierEnum';
+
+/**
+ * Response de GET /private/products/:retailerId/:sku — validar que el producto existe + status.
+ * Incluye los campos que los downstream consumen: `eligibleFinanciers` (wizard F2 paso 4)
+ * y la config MDM (device router F4+). Shape de salida → sin class-validator.
+ */
+export class ValidateProductResponse {
+    productId!: string;
+    retailerId!: string;
+    sku!: string;
+    status!: ProductStatusEnum;
+    tier!: ProductTierEnum;
+    eligibleFinanciers!: string[];
+    mdmEnabled!: boolean;
+    mdmProvider!: MdmProviderEnum | null;
+    mdmLockMode!: MdmLockModeEnum | null;
+}

package/src/retailCatalog/enums/InventoryItemStatusEnum.ts

@@ -0,0 +1,18 @@
+/**
+ * Estado de una unidad física (IMEI) en inventario.
+ * Transiciones: AVAILABLE → RESERVED → SOLD/AVAILABLE (release); RETURNED desde SOLD; DAMAGED.
+ * @enum {string}
+ *
+ * @property {string} AVAILABLE - Disponible en stock.
+ * @property {string} RESERVED - Reservada para una venta en curso.
+ * @property {string} SOLD - Vendida.
+ * @property {string} RETURNED - Devuelta por el cliente.
+ * @property {string} DAMAGED - Dañada, fuera de stock vendible.
+ */
+export enum InventoryItemStatusEnum {
+    AVAILABLE = 'AVAILABLE',
+    RESERVED = 'RESERVED',
+    SOLD = 'SOLD',
+    RETURNED = 'RETURNED',
+    DAMAGED = 'DAMAGED',
+}

package/src/retailCatalog/enums/MdmLockModeEnum.ts

@@ -0,0 +1,17 @@
+/**
+ * Modo de bloqueo MDM. Valores del flow 04 de F1 (ONDEMAND/SCHEDULED).
+ *
+ * TD-007: el `DeviceLockModeEnum` del dominio `mdm` hoy tiene TEMPORARY/FIRM (semántica
+ * distinta: qué tan firme es el lock, no cuándo se dispara). Reconciliación pendiente con
+ * el dueño del dominio `mdm` (decidir reuso vs enum nuevo). En F1 el campo es pasivo
+ * (se guarda, no se ejerce) → no bloqueante.
+ *
+ * @enum {string}
+ *
+ * @property {string} ONDEMAND - El bloqueo se dispara bajo demanda.
+ * @property {string} SCHEDULED - El bloqueo se dispara de forma programada.
+ */
+export enum MdmLockModeEnum {
+    ONDEMAND = 'ONDEMAND',
+    SCHEDULED = 'SCHEDULED',
+}

package/src/retailCatalog/enums/MdmProviderEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * Proveedor MDM (Mobile Device Management) para el enrolamiento de dispositivos (F4+).
+ * @enum {string}
+ *
+ * @property {string} TRUSTONIC - Proveedor Trustonic.
+ * @property {string} DATACULTR - Proveedor Datacultr.
+ */
+export enum MdmProviderEnum {
+    TRUSTONIC = 'TRUSTONIC',
+    DATACULTR = 'DATACULTR',
+}

package/src/retailCatalog/enums/ProductStatusEnum.ts

@@ -0,0 +1,13 @@
+/**
+ * Estado del producto en el catálogo.
+ * @enum {string}
+ *
+ * @property {string} ACTIVE - Producto activo y vendible.
+ * @property {string} INACTIVE - Producto inactivo temporalmente.
+ * @property {string} DISCONTINUED - Producto descontinuado.
+ */
+export enum ProductStatusEnum {
+    ACTIVE = 'ACTIVE',
+    INACTIVE = 'INACTIVE',
+    DISCONTINUED = 'DISCONTINUED',
+}

package/src/retailCatalog/enums/ProductTierEnum.ts

@@ -0,0 +1,15 @@
+/**
+ * Tier comercial del producto (segmenta catálogo por rango de precio/posicionamiento).
+ * @enum {string}
+ *
+ * @property {string} LOW - Gama de entrada.
+ * @property {string} MID - Gama media.
+ * @property {string} HIGH - Gama alta.
+ * @property {string} PREMIUM - Gama premium.
+ */
+export enum ProductTierEnum {
+    LOW = 'LOW',
+    MID = 'MID',
+    HIGH = 'HIGH',
+    PREMIUM = 'PREMIUM',
+}

package/src/retailCatalog/index.ts

@@ -0,0 +1,34 @@
+export * from './enums/ProductTierEnum';
+export * from './enums/ProductStatusEnum';
+export * from './enums/InventoryItemStatusEnum';
+export * from './enums/MdmProviderEnum';
+export * from './enums/MdmLockModeEnum';
+
+// Constantes del dominio
+export * from './constants/SkuPattern';
+
+// Validators custom
+export * from './validators/IsMdmCoherentConstraint';
+
+// Entity DTOs
+export * from './dtos/Product';
+export * from './dtos/InventoryItem';
+
+// Request DTOs (input validado por endpoint)
+export * from './dtos/requests/CreateProductRequest';
+export * from './dtos/requests/UpdateProductRequest';
+export * from './dtos/requests/UpdateProductStatusRequest';
+export * from './dtos/requests/ListProductsQuery';
+export * from './dtos/requests/RegisterInventoryRequest';
+export * from './dtos/requests/TransferInventoryRequest';
+export * from './dtos/requests/ChangeInventoryStatusRequest';
+
+// Response DTOs
+export * from './dtos/responses/ProductResponse';
+export * from './dtos/responses/InventoryItemResponse';
+export * from './dtos/responses/ImportCsvFailure';
+export * from './dtos/responses/ImportCsvResult';
+
+// Validation DTOs (shapes de endpoints privados)
+export * from './dtos/validation/ValidateProductResponse';
+export * from './dtos/validation/ValidateInventoryResponse';

package/src/retailCatalog/validators/IsMdmCoherentConstraint.ts

@@ -0,0 +1,25 @@
+import {
+    ValidatorConstraint,
+    type ValidationArguments,
+    type ValidatorConstraintInterface,
+} from 'class-validator';
+
+/**
+ * Coherencia de la config MDM del producto:
+ * - mdmEnabled === true  → mdmProvider y mdmLockMode obligatorios.
+ * - mdmEnabled !== true   → mdmProvider y mdmLockMode deben omitirse (null/undefined).
+ */
+@ValidatorConstraint({ name: 'isMdmCoherent', async: false })
+export class IsMdmCoherentConstraint implements ValidatorConstraintInterface {
+    validate(_value: unknown, args: ValidationArguments): boolean {
+        const o = args.object as { mdmEnabled?: boolean; mdmProvider?: unknown; mdmLockMode?: unknown };
+        if (o.mdmEnabled === true) {
+            return o.mdmProvider != null && o.mdmLockMode != null;
+        }
+        return o.mdmProvider == null && o.mdmLockMode == null;
+    }
+
+    defaultMessage(): string {
+        return 'Configuración MDM incoherente: con mdmEnabled=true se requieren mdmProvider y mdmLockMode; con mdmEnabled=false deben omitirse';
+    }
+}

package/src/retailOrg/dtos/validation/CollectorValidationDto.ts

@@ -0,0 +1,22 @@
+import type { CollectorSeniorityEnum } from '../../enums/CollectorSeniorityEnum';
+import type { RetailUserStatusEnum } from '../../enums/RetailUserStatusEnum';
+
+/**
+ * Shape mínimo de un cobrador retail que devuelve el endpoint privado de validación de cobradores
+ * (consumido por loan-collector-assignment-business vía @fiado/api-invoker) para alimentar el
+ * algoritmo de asignación de cartera.
+ *
+ * `coverageStoreIds` va requerido (siempre presente; si el cobrador aún no cubre tiendas, `[]`).
+ *
+ * `collectorSeniority` es OPCIONAL: el modelo de datos no obliga a que un usuario con
+ * `commissionTier === 'collector'` tenga seniority poblado, así que un cobrador sin seniority es
+ * válido. Las estrategias de asignación BY_STORE / BY_LOAD / ROUND_ROBIN no lo necesitan; solo
+ * BY_SENIORITY lo usa para rankear (y ahí un cobrador sin seniority simplemente no rankea).
+ */
+export interface CollectorValidationDto {
+    retailUserId: string;
+    coverageStoreIds: string[];
+    collectorSeniority?: CollectorSeniorityEnum;
+    status: RetailUserStatusEnum;
+    commissionTier: string;
+}

package/src/retailOrg/index.ts

@@ -17,6 +17,7 @@ export * from './dtos/RetailUser';
 export * from './dtos/validation/RetailerValidationDto';
 export * from './dtos/validation/StoreValidationDto';
 export * from './dtos/validation/RetailUserValidationDto';
+export * from './dtos/validation/CollectorValidationDto';
 
 // Paginación genérica
 export * from './dtos/PaginatedResult';