@fiado/type-kit 3.578.0 → 3.579.0

package/src/retailIntegration/models/RetailSystemSale.ts

@@ -1,51 +1,59 @@
-import { RetailLinePaymentTypeEnum, RetailPaymentMethodEnum, RetailSaleFinancierEnum, RetailSaleTypeEnum } from '../enums';
+import { Type } from 'class-transformer';
+import { ArrayNotEmpty, IsArray, IsIn, IsInt, IsObject, IsString, Matches, Min, Validate, ValidateIf, ValidateNested } from 'class-validator';
+import { RETAIL_DECIMAL_PATTERN, RETAIL_ENTITY_ID_PATTERN, RETAIL_SKU_PATTERN } from '../constants/retailIntegrationLimits';
+import { RetailCurrencyEnum, RetailLinePaymentTypeEnum, RetailPaymentMethodEnum, RetailSaleFinancierEnum, RetailSaleLineRoleEnum, RetailSaleTypeEnum } from '../enums';
+import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
+import { HasUniqueKeys, isNullOrValidated } from '../validators/payloadValidators';
 import { RetailCurrency } from './RetailSystemProduct';
 
 export type RetailSaleType = `${RetailSaleTypeEnum}`;
 export type RetailSaleFinancier = `${RetailSaleFinancierEnum}`;
 export type RetailPaymentMethod = `${RetailPaymentMethodEnum}`;
 export type RetailLinePaymentType = `${RetailLinePaymentTypeEnum}`;
+export type RetailSaleLineRole = `${RetailSaleLineRoleEnum}`;
 
-export interface RetailSystemSaleCustomer {
-    customerId: string;
-    names: string;
-    paternalLastName: string;
-    maternalLastName: string | null;
-    phone: string;
+export class RetailSystemSaleCustomer {
+    @IsString() @Matches(/\S/) customerId!: string;
+    @IsString() @Matches(/\S/) names!: string;
+    @IsString() @Matches(/\S/) paternalLastName!: string;
+    @ValidateIf(isNullOrValidated) @IsString() maternalLastName!: string | null;
+    @IsString() @Matches(/\S/) phone!: string;
 }
 
-export interface RetailSystemSaleComponent {
-    sku: string;
-    qty: number;
-    identifiers: string[];
+export class RetailSystemSaleComponent {
+    @IsString() @Matches(RETAIL_SKU_PATTERN) sku!: string;
+    @IsInt() @Min(1) qty!: number;
+    @IsArray() @IsString({ each: true }) @Matches(/\S/, { each: true }) identifiers!: string[];
 }
 
-export interface RetailSystemSaleLine {
-    lineId: string;
-    sku: string;
-    qty: number;
-    basePrice: string;
-    discount: string;
-    paymentType: RetailLinePaymentType;
-    financedAmount: string;
-    role: 'GIFT' | null;
-    components: RetailSystemSaleComponent[];
+export class RetailSystemSaleLine {
+    @IsString() @Matches(/\S/) lineId!: string;
+    @IsString() @Matches(RETAIL_SKU_PATTERN) sku!: string;
+    @IsInt() @Min(1) qty!: number;
+    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) basePrice!: string;
+    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) discount!: string;
+    @IsIn(Object.values(RetailLinePaymentTypeEnum)) paymentType!: RetailLinePaymentType;
+    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) financedAmount!: string;
+    @ValidateIf(isNullOrValidated) @IsIn(Object.values(RetailSaleLineRoleEnum)) role!: RetailSaleLineRole | null;
+    @IsArray() @ValidateNested({ each: true }) @Type(() => RetailSystemSaleComponent) components!: RetailSystemSaleComponent[];
 }
 
-/** Cuerpo de `POST /sales` de la doc; `saleId` es la llave de idempotencia. */
-export interface RetailSystemSale {
-    saleId: string;
-    folio: string;
-    storeId: string;
-    sellerRetailUserId: string;
-    soldAt: string;
-    saleType: RetailSaleType;
-    financier: RetailSaleFinancier;
-    creditId: string | null;
-    currencyId: RetailCurrency;
-    customer: RetailSystemSaleCustomer;
-    equipmentPrice: string;
-    amountPaid: string;
-    paymentMethod: RetailPaymentMethod | null;
-    lines: RetailSystemSaleLine[];
+/** Cuerpo de `POST /sales` de la doc y de `privateRegisterRetailSale`; `saleId` es la llave de idempotencia. */
+export class RetailSystemSale {
+    @IsString() @Matches(/\S/) saleId!: string;
+    @IsString() @Matches(/\S/) folio!: string;
+    @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) storeId!: string;
+    @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) sellerRetailUserId!: string;
+    @Validate(IsIsoDateTimeWithZone) soldAt!: string;
+    @IsIn(Object.values(RetailSaleTypeEnum)) saleType!: RetailSaleType;
+    @IsIn(Object.values(RetailSaleFinancierEnum)) financier!: RetailSaleFinancier;
+    @ValidateIf(isNullOrValidated) @IsString() @Matches(/\S/) creditId!: string | null;
+    @IsIn(Object.values(RetailCurrencyEnum)) currencyId!: RetailCurrency;
+    @IsObject() @ValidateNested() @Type(() => RetailSystemSaleCustomer) customer!: RetailSystemSaleCustomer;
+    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) equipmentPrice!: string;
+    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) amountPaid!: string;
+    @ValidateIf(isNullOrValidated) @IsIn(Object.values(RetailPaymentMethodEnum)) paymentMethod!: RetailPaymentMethod | null;
+
+    @IsArray() @ArrayNotEmpty() @ValidateNested({ each: true }) @Type(() => RetailSystemSaleLine) @Validate(HasUniqueKeys, ['lineId'])
+    lines!: RetailSystemSaleLine[];
 }

package/src/retailOrg/dtos/Retailer.ts

@@ -1,9 +1,10 @@
 import { Expose, Type } from 'class-transformer';
-import { IsEmail, IsEnum, IsObject, IsString, Length, Matches } from 'class-validator';
+import { IsEmail, IsEnum, IsObject, IsOptional, IsString, Length, Matches } from 'class-validator';
 import { LocationAddress } from '../../address/dtos/LocationAddress';
 import { regexIso8601 } from '../../helpers/constans/regex';
 import { RetailerStatusEnum } from '../enums/RetailerStatusEnum';
 import { RetailerTypeEnum } from '../enums/RetailerTypeEnum';
+import { RetailIntegrationSystemEnum } from '../enums/RetailIntegrationSystemEnum';
 
 /**
  * Retailer — nodo raíz de la organización comercial SureKeep (cadena / subdistribuidor / franquicia).
@@ -78,4 +79,21 @@ export class Retailer {
     @Expose()
     @IsString()
     updatedBy!: string;
+
+    /** Bandera «integrado»: presente solo si el retailer ya se activó con un sistema externo. */
+    @Expose()
+    @IsOptional()
+    @IsEnum(RetailIntegrationSystemEnum)
+    integrationSystem?: RetailIntegrationSystemEnum;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(regexIso8601, { message: 'integrationActivatedAt debe ser una fecha ISO 8601' })
+    integrationActivatedAt?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    integrationActivatedBy?: string;
 }

package/src/retailOrg/dtos/requests/ActivateRetailerIntegrationRequest.ts

@@ -0,0 +1,10 @@
+import { Expose } from 'class-transformer';
+import { IsEnum } from 'class-validator';
+import { RetailIntegrationSystemEnum } from '../../enums/RetailIntegrationSystemEnum';
+
+/** Body de POST /retailers/:retailerId/integration/activate. */
+export class ActivateRetailerIntegrationRequest {
+    @Expose()
+    @IsEnum(RetailIntegrationSystemEnum)
+    integrationSystem!: RetailIntegrationSystemEnum;
+}

package/src/retailOrg/dtos/responses/ActivateRetailerIntegrationResponse.ts

@@ -0,0 +1,5 @@
+import type { Retailer } from '../Retailer';
+
+/** Respuesta de POST /retailers/:retailerId/integration/activate: el Retailer con la bandera ya sellada. */
+export type ActivateRetailerIntegrationResponse = Retailer &
+    Required<Pick<Retailer, 'integrationSystem' | 'integrationActivatedAt' | 'integrationActivatedBy'>>;

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

@@ -1,5 +1,6 @@
 import type { RetailerStatusEnum } from '../../enums/RetailerStatusEnum';
 import type { RetailerTypeEnum } from '../../enums/RetailerTypeEnum';
+import type { RetailIntegrationSystemEnum } from '../../enums/RetailIntegrationSystemEnum';
 
 /**
  * Shape mínimo que devuelve el endpoint privado de validación de retailer (consumido por otros
@@ -12,4 +13,7 @@ export interface RetailerValidationDto {
     type: RetailerTypeEnum;
     status: RetailerStatusEnum;
     parentId: string;
+    /** Bandera «integrado»; ausente si el retailer no está integrado. */
+    integrationSystem?: RetailIntegrationSystemEnum;
+    integrationActivatedAt?: string;
 }

package/src/retailOrg/enums/RetailIntegrationSystemEnum.ts

@@ -0,0 +1,4 @@
+/** Sistema externo que administra la organización de un retailer integrado. */
+export enum RetailIntegrationSystemEnum {
+    ZENTRAL = 'ZENTRAL',
+}

package/src/retailOrg/index.ts

@@ -6,6 +6,7 @@ export * from './enums/RetailUserStatusEnum';
 export * from './enums/EmploymentTypeEnum';
 export * from './enums/CollectorSeniorityEnum';
 export * from './enums/RetailUserWalletLinkMethodEnum';
+export * from './enums/RetailIntegrationSystemEnum';
 // F3 — Portal Admin VentasLuga (metas de venta del periodo)
 export * from './enums/GoalTargetTypeEnum';
 
@@ -56,6 +57,7 @@ export * from './dtos/requests/GoalPathParams';
 export * from './dtos/requests/PrivateGoalListQuery';
 export * from './dtos/requests/KpiQuery';
 export * from './dtos/requests/PrivateSellerListQuery';
+export * from './dtos/requests/ActivateRetailerIntegrationRequest';
 
 // Response DTOs
 export * from './dtos/responses/RetailerHierarchyResponse';
@@ -66,3 +68,4 @@ export * from './dtos/responses/StoreKpiResponse';
 export * from './dtos/responses/SellerKpiResponse';
 export * from './dtos/responses/LookupRetailUserWalletResponse';
 export * from './dtos/responses/PrivateRetailUserWalletResponse';
+export * from './dtos/responses/ActivateRetailerIntegrationResponse';

package/src/retailWizard/dtos/Sale.ts

@@ -4,6 +4,8 @@ import type { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
 import type { SaleChannelEnum } from '../enums/SaleChannelEnum';
 import type { ExternalProviderEnum } from '../enums/ExternalProviderEnum';
 import type { CentralSyncStatusEnum } from '../enums/CentralSyncStatusEnum';
+import type { CentralCancelStatusEnum } from '../enums/CentralCancelStatusEnum';
+import type { CentralLiveCheckEnum } from '../enums/CentralLiveCheckEnum';
 import type { SalePaymentDetail } from './SalePaymentDetail';
 import type { SaleLine } from './SaleLine';
 import type { SalePromotionRef } from '../../retailPromotions/dtos/SalePromotionRef';
@@ -64,6 +66,29 @@ export interface Sale {
   cardDeliveryId: string | null;
   centralSyncStatus: CentralSyncStatusEnum;
   centralTag: string | null;
+  /** Estado de la cancelación en Central; ausente si la venta no se ha cancelado. */
+  centralCancelStatus?: CentralCancelStatusEnum;
+  /** ISO; primer intento de envío, se sella una sola vez. */
+  centralFirstAttemptAt?: string;
+  /** ISO; inicio de la ventana de 24 h de reintentos, el reenvío la reinicia. */
+  centralRetryWindowStartAt?: string;
+  /** ISO; último intento de envío. */
+  centralLastAttemptAt?: string;
+  /** ISO; hasta cuándo el consumidor tiene tomada la venta. */
+  centralLeaseUntil?: string;
+  centralAttempts?: number;
+  /** Code del rechazo o del último error de Central. */
+  centralLastErrorCode?: string;
+  /** ISO; cuándo Central aceptó la venta. */
+  centralAcceptedAt?: string;
+  /** ISO; primer intento de la cancelación, se sella una sola vez. */
+  centralCancelFirstAttemptAt?: string;
+  /** ISO; inicio de la ventana de 24 h de la cancelación, el reenvío la reinicia. */
+  centralCancelRetryWindowStartAt?: string;
+  /** ISO; cuándo Central aceptó la cancelación. */
+  centralCancelAcceptedAt?: string;
+  /** Resultado de la consulta en vivo, copiado de la sesión al cerrar. */
+  centralLiveCheck?: CentralLiveCheckEnum;
   status: SaleStatusEnum;
   cancelledAt: string | null;
   /** Reason OBLIGATORIO en cancelación (AuditTrail) — flujo C. */

package/src/retailWizard/dtos/WizardReservedLine.ts

@@ -1,3 +1,4 @@
+import type { InventoryItemStatusEnum } from '../../retailCatalog/enums/InventoryItemStatusEnum';
 import type { MdmProviderEnum } from '../../retailCatalog/enums/MdmProviderEnum';
 import type { ReservedComponent } from '../../retailCatalog/dtos/responses/ReserveStockResponse';
 import type { LinePaymentTypeEnum } from '../enums/LinePaymentTypeEnum';
@@ -12,6 +13,8 @@ export interface WizardReservedLine extends WizardLinePromotionFields {
     sku: string;
     qty: number;
     status: WizardLineStatusEnum;
+    /** Solo en LOST: estado en que Central dejó la pieza (SOLD, IN_TRANSIT o DAMAGED). */
+    lostReason?: InventoryItemStatusEnum;
     /** Llave de idempotencia de la reserva; una nueva por cada intento. */
     reservationId: string;
     /** Vencimiento de la reserva; una línea PENDING nace con ahora + 30 min. */

package/src/retailWizard/dtos/WizardSession.ts

@@ -1,4 +1,5 @@
 import type { SalePromotionRef } from '../../retailPromotions/dtos/SalePromotionRef';
+import type { CentralLiveCheckEnum } from '../enums/CentralLiveCheckEnum';
 import type { WizardStateEnum } from '../enums/WizardStateEnum';
 import type { WizardStepEnum } from '../enums/WizardStepEnum';
 import type { FiadoPhoneStatusEnum } from '../enums/FiadoPhoneStatusEnum';
@@ -152,6 +153,8 @@ export interface WizardSession {
   /** Contexto de crédito (pista SOFOM, pasos 04-09): PUNTEROS al dominio loan-*. Null en contado/externa. */
   loan: WizardLoan | null;
   saleId: string | null;
+  /** Resultado de la consulta en vivo a Central; la TX de cierre lo copia a la venta. */
+  centralLiveCheck?: CentralLiveCheckEnum;
   /** Prospecto vinculado (si la sesión se reanudó desde un prospecto): se cierra al cerrar la venta (D-prospecto). */
   prospectId: string | null;
   cancelReason: string | null;

package/src/retailWizard/enums/CentralCancelStatusEnum.ts

@@ -0,0 +1,18 @@
+/**
+ * Estado de la cancelación de la venta en Central.
+ *
+ * PENDING - Por enviar o en reintento.
+ * SENDING - Tomada por el consumidor, envío en curso.
+ * ACCEPTED - Central aceptó la cancelación.
+ * REJECTED - Central rechazó la cancelación.
+ * FAILED - Se agotó la ventana de reintentos.
+ * NOT_SENT - No se envía: la venta nunca quedó en Central.
+ */
+export enum CentralCancelStatusEnum {
+    PENDING = 'PENDING',
+    SENDING = 'SENDING',
+    ACCEPTED = 'ACCEPTED',
+    REJECTED = 'REJECTED',
+    FAILED = 'FAILED',
+    NOT_SENT = 'NOT_SENT',
+}

package/src/retailWizard/enums/CentralLiveCheckEnum.ts

@@ -0,0 +1,10 @@
+/**
+ * Resultado de la consulta en vivo a Central antes de cerrar la venta.
+ *
+ * VERIFIED - Central confirmó la pieza a tiempo.
+ * UNVERIFIED - Central no contestó a tiempo; la venta sigue igual.
+ */
+export enum CentralLiveCheckEnum {
+    VERIFIED = 'VERIFIED',
+    UNVERIFIED = 'UNVERIFIED',
+}

package/src/retailWizard/enums/CentralSyncStatusEnum.ts

@@ -2,13 +2,19 @@
  * Estado de sincronización de la venta con Central (local-first; badge en BO). SureKeep Fase 2 — pista Retail.
  *
  * PENDING - Aún no sincronizada.
- * SENT - Enviada a Central.
+ * SENT - Enviada a Central (sin uso: lo reemplazan SENDING y ACCEPTED).
  * FAILED - Falló la sincronización.
  * N_A - No aplica (p. ej. derivación externa).
+ * SENDING - Tomada por el consumidor, envío en curso.
+ * ACCEPTED - Central la aceptó.
+ * REJECTED - Central la rechazó con un 4xx de su catálogo.
  */
 export enum CentralSyncStatusEnum {
     PENDING = 'PENDING',
     SENT = 'SENT',
     FAILED = 'FAILED',
     N_A = 'N_A',
+    SENDING = 'SENDING',
+    ACCEPTED = 'ACCEPTED',
+    REJECTED = 'REJECTED',
 }

package/src/retailWizard/enums/RetailCentralOutboundMessageTypeEnum.ts

@@ -0,0 +1,5 @@
+/** Tipo de mensaje que el wizard publica en RetailCentralOutboundQueue. */
+export enum RetailCentralOutboundMessageTypeEnum {
+    CENTRAL_SALE_REGISTER = 'CENTRAL_SALE_REGISTER',
+    CENTRAL_SALE_CANCEL = 'CENTRAL_SALE_CANCEL',
+}

package/src/retailWizard/enums/WizardLineStatusEnum.ts

@@ -6,4 +6,6 @@ export enum WizardLineStatusEnum {
     RESERVED = 'RESERVED',
     /** Marcada para liberar; pago y enganche la rechazan. */
     RELEASING = 'RELEASING',
+    /** Central vendió, traspasó o retiró la pieza; no se puede cobrar, firmar ni cerrar con ella. */
+    LOST = 'LOST',
 }

package/src/retailWizard/events/RetailCentralOutboundMessage.ts

@@ -0,0 +1,24 @@
+import { IsEnum, IsNotEmpty, IsString } from 'class-validator';
+import { RetailCentralOutboundMessageTypeEnum } from '../enums/RetailCentralOutboundMessageTypeEnum';
+
+/** Aviso a Central de una venta por registrar o cancelar; el consumidor lee la venta por saleId. */
+export class RetailCentralOutboundMessage {
+    @IsEnum(RetailCentralOutboundMessageTypeEnum)
+    messageType!: RetailCentralOutboundMessageTypeEnum;
+
+    @IsString()
+    @IsNotEmpty()
+    tenantId!: string;
+
+    @IsString()
+    @IsNotEmpty()
+    retailerId!: string;
+
+    @IsString()
+    @IsNotEmpty()
+    storeId!: string;
+
+    @IsString()
+    @IsNotEmpty()
+    saleId!: string;
+}

package/src/retailWizard/index.ts

@@ -13,6 +13,8 @@ export * from './enums/SalePaymentMethodEnum';
 export * from './enums/RefundStatusEnum';
 export * from './enums/SaleStatusEnum';
 export * from './enums/CentralSyncStatusEnum';
+export * from './enums/CentralCancelStatusEnum';
+export * from './enums/CentralLiveCheckEnum';
 export * from './enums/ProspectStatusEnum';
 export * from './enums/PendingReasonEnum';
 export * from './enums/OccupationEnum';
@@ -199,11 +201,13 @@ export * from './events/SaleCancelledV2';
 export * from './events/SessionExpiredV1';
 export * from './enums/RetailPromotionInboundMessageTypeEnum';
 export * from './enums/RetailCommissionInboundMessageTypeEnum';
+export * from './enums/RetailCentralOutboundMessageTypeEnum';
 export * from './events/RetailPromotionInboundMessage';
 export * from './events/RetailPromotionAccountOpenedMessage';
 export * from './events/RetailPromotionInstallmentPaidMessage';
 export * from './events/RetailPromotionQueueMessage';
 export * from './events/RetailCommissionInboundMessage';
+export * from './events/RetailCentralOutboundMessage';
 
 // Lookup privado por lote (GET /private/wizard-sessions/batch)
 export * from './enums/WizardSessionLookupStatusEnum';