@fiado/type-kit 3.630.0 → 3.632.0

package/src/retailWizard/dtos/SalePayment.ts

@@ -0,0 +1,55 @@
+import { Expose } from 'class-transformer';
+import { IsBoolean, IsEnum, IsInt, Matches, Min, Validate, ValidateIf } from 'class-validator';
+import {
+    RETAIL_CARD_LAST4_PATTERN,
+    RETAIL_CLABE_PATTERN,
+    RETAIL_SALE_ID_TEXT_PATTERN,
+    RETAIL_SPEI_TRACKING_KEY_PATTERN,
+} from '../../retailIntegration/constants/retailIntegrationLimits';
+import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+import { OnlyForPaymentMethodConstraint } from '../validators/OnlyForPaymentMethodConstraint';
+
+const { CASH, CARD, WIRE } = SalePaymentMethodEnum;
+const hasValue = (field: keyof SalePayment) => (o: SalePayment) => o[field] != null;
+
+/** Un pago del cobro. El comprobante es opcional: si viene se valida y solo en su medio; si no, `null` o ausente. */
+export class SalePayment {
+    @Expose()
+    @IsEnum(SalePaymentMethodEnum)
+    method!: SalePaymentMethodEnum;
+
+    @Expose()
+    @IsInt()
+    @Min(1)
+    amountCents!: number;
+
+    @Expose()
+    @ValidateIf(hasValue('cashConfirmedInRegister'))
+    @IsBoolean()
+    @Validate(OnlyForPaymentMethodConstraint, [CASH])
+    cashConfirmedInRegister?: boolean | null;
+
+    @Expose()
+    @ValidateIf(hasValue('cardLast4'))
+    @Matches(RETAIL_CARD_LAST4_PATTERN)
+    @Validate(OnlyForPaymentMethodConstraint, [CARD])
+    cardLast4?: string | null;
+
+    @Expose()
+    @ValidateIf(hasValue('authCode'))
+    @Matches(RETAIL_SALE_ID_TEXT_PATTERN)
+    @Validate(OnlyForPaymentMethodConstraint, [CARD])
+    authCode?: string | null;
+
+    @Expose()
+    @ValidateIf(hasValue('speiTrackingKey'))
+    @Matches(RETAIL_SPEI_TRACKING_KEY_PATTERN)
+    @Validate(OnlyForPaymentMethodConstraint, [WIRE])
+    speiTrackingKey?: string | null;
+
+    @Expose()
+    @ValidateIf(hasValue('senderClabe'))
+    @Matches(RETAIL_CLABE_PATTERN)
+    @Validate(OnlyForPaymentMethodConstraint, [WIRE])
+    senderClabe?: string | null;
+}

package/src/retailWizard/dtos/SalePaymentDetail.ts

@@ -5,6 +5,7 @@ import { IsBoolean, IsOptional, IsString } from 'class-validator';
  * Detalle del pago según el medio (`Sale.paymentDetail`): efectivo `{cashConfirmedInRegister}` ·
  * tarjeta `{cardLast4, authCode}` · SPEI `{speiTrackingKey, senderClabe?}`. SureKeep Fase 2 — pista Retail.
  */
+/** @deprecated Usa `SalePayment`, un elemento por pago. */
 export class SalePaymentDetail {
     @Expose()
     @IsOptional()

package/src/retailWizard/dtos/SellerPendingRefundItem.ts

@@ -1,5 +1,6 @@
 import { RefundStatusEnum } from '../enums/RefundStatusEnum';
 import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+import type { SalePayment } from './SalePayment';
 
 /** Un reembolso de enganche de la tienda en el Portal Vendedor (GET /portal/pending-refunds). */
 export interface SellerPendingRefundItem {
@@ -10,8 +11,12 @@ export interface SellerPendingRefundItem {
     creditId: string | null;
     folio: string | null;
     refundPendingCents: number;
-    /** `null` = el registro no guardó con qué se cobró el enganche; no se puede marcar entregado. */
+    /**
+     * @deprecated Usa `payments`. `null` = el registro no guardó con qué se cobró el enganche; no se puede marcar entregado.
+     */
     paymentMethod: SalePaymentMethodEnum | null;
+    /** Pagos con que se cobró el enganche; ausente en registros anteriores al campo. */
+    payments?: SalePayment[] | null;
     status: RefundStatusEnum;
     /** `true` si el vendedor puede marcarlo entregado: efectivo y pendiente. */
     deliverable: boolean;

package/src/retailWizard/dtos/WizardPayment.ts

@@ -2,9 +2,12 @@ import { Expose } from 'class-transformer';
 import { IsEnum, IsInt, IsOptional, IsString, Matches, Min } from 'class-validator';
 import { regexIso8601 } from '../../helpers/constans/regex';
 import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+import { IsSalePaymentList } from '../validators/IsSalePaymentList';
+import { SalePayment } from './SalePayment';
 
 /** Registro del pago de contado dentro de la sesión (`WizardSession.payment`). SureKeep Fase 2 — pista Retail. */
 export class WizardPayment {
+    /** @deprecated Usa `payments`; con varios pagos lleva el método del primero. */
     @Expose()
     @IsEnum(SalePaymentMethodEnum)
     method!: SalePaymentMethodEnum;
@@ -14,11 +17,18 @@ export class WizardPayment {
     @Min(0)
     amountCents!: number;
 
+    /** @deprecated Usa `payments`; es el comprobante como texto JSON. */
     @Expose()
     @IsOptional()
     @IsString()
     detail?: string;
 
+    /** Pagos del cobro (1 a 3); ausente en sesiones anteriores al campo. */
+    @Expose()
+    @IsOptional()
+    @IsSalePaymentList()
+    payments?: SalePayment[];
+
     @Expose()
     @IsString()
     @Matches(regexIso8601, { message: 'paidAt debe ser una fecha ISO 8601' })

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

@@ -3,19 +3,22 @@ import {
   ArrayMaxSize,
   ArrayMinSize,
   IsArray,
-  IsDefined,
   IsEnum,
   IsInt,
+  IsOptional,
   Min,
+  ValidateIf,
   ValidateNested,
 } from 'class-validator';
 import { SalePaymentMethodEnum } from '../../enums/SalePaymentMethodEnum';
 import { SalePaymentDetail } from '../SalePaymentDetail';
 import { AccessorySaleLine } from '../AccessorySaleLine';
+import { SalePayment } from '../SalePayment';
+import { IsSalePaymentList } from '../../validators/IsSalePaymentList';
 
 /**
  * POST /wizard/accessory-sales — cierra la venta de mostrador, sin cliente.
- * `amountCents` es lo cobrado en caja y debe igualar la suma del catálogo.
+ * `amountCents` es lo cobrado en caja: iguala la suma del catálogo y la de `payments`.
  */
 export class CreateAccessorySaleRequest {
   @Expose()
@@ -26,18 +29,27 @@ export class CreateAccessorySaleRequest {
   @Type(() => AccessorySaleLine)
   lines!: AccessorySaleLine[];
 
+  /** @deprecated Usa `payments`; obligatorio solo si `payments` no viene. */
   @Expose()
+  @ValidateIf((o: { payments?: unknown; paymentMethod?: unknown }) => o.payments == null || o.paymentMethod !== undefined)
   @IsEnum(SalePaymentMethodEnum)
-  paymentMethod!: SalePaymentMethodEnum;
+  paymentMethod?: SalePaymentMethodEnum;
 
   @Expose()
   @IsInt()
   @Min(0)
   amountCents!: number;
 
+  /** @deprecated Usa el comprobante de cada elemento de `payments`. */
   @Expose()
-  @IsDefined()
+  @IsOptional()
   @ValidateNested()
   @Type(() => SalePaymentDetail)
-  paymentDetail!: SalePaymentDetail;
+  paymentDetail?: SalePaymentDetail;
+
+  /** Pagos del cobro (1 a 3); si viene, manda sobre `paymentMethod` y `paymentDetail`. */
+  @Expose()
+  @IsOptional()
+  @IsSalePaymentList()
+  payments?: SalePayment[];
 }

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

@@ -1,7 +1,9 @@
 import { Expose, Type } from 'class-transformer';
-import { IsEnum, IsInt, IsOptional, Min, ValidateNested } from 'class-validator';
+import { IsEnum, IsInt, IsOptional, Min, ValidateIf, ValidateNested } from 'class-validator';
 import { SalePaymentMethodEnum } from '../../enums/SalePaymentMethodEnum';
 import { SalePaymentDetail } from '../SalePaymentDetail';
+import { SalePayment } from '../SalePayment';
+import { IsSalePaymentList } from '../../validators/IsSalePaymentList';
 
 /**
  * POST /wizard/sessions/:id/down-payment — cobro del ENGANCHE de la venta a crédito (paso 07,
@@ -9,22 +11,31 @@ import { SalePaymentDetail } from '../SalePaymentDetail';
  * `amountCents == downPaymentCents` del crédito (`loan-credit GET /credits/{id}`), NO el precio
  * full. Idempotente por sesión. El folio `SK-…-ENG-…` lo genera el server (no viaja en el body).
  * Al confirmar, el wizard marca la condición 1 del checklist (`activate-check { downPayment }`).
- * SPEI: el vendedor captura el comprobante (`speiTrackingKey`+`senderClabe`) y avanza.
+ * El comprobante de tarjeta y SPEI es opcional; `amountCents` es la suma de `payments`.
  * SureKeep Fase 2 — pista SOFOM.
  */
 export class DownPaymentRequest {
+    /** @deprecated Usa `payments`; obligatorio solo si `payments` no viene. */
     @Expose()
+    @ValidateIf((o: { payments?: unknown; method?: unknown }) => o.payments == null || o.method !== undefined)
     @IsEnum(SalePaymentMethodEnum)
-    method!: SalePaymentMethodEnum;
+    method?: SalePaymentMethodEnum;
 
     @Expose()
     @IsInt()
     @Min(0)
     amountCents!: number;
 
+    /** @deprecated Usa el comprobante de cada elemento de `payments`. */
     @Expose()
     @IsOptional()
     @Type(() => SalePaymentDetail)
     @ValidateNested()
     detail?: SalePaymentDetail;
+
+    /** Pagos del cobro (1 a 3); si viene, manda sobre `method` y `detail`. */
+    @Expose()
+    @IsOptional()
+    @IsSalePaymentList()
+    payments?: SalePayment[];
 }

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

@@ -1,7 +1,9 @@
 import { Expose, Type } from 'class-transformer';
-import { IsEnum, IsInt, IsOptional, ValidateNested, Min } from 'class-validator';
+import { IsEnum, IsInt, IsOptional, ValidateIf, ValidateNested, Min } from 'class-validator';
 import { SalePaymentMethodEnum } from '../../enums/SalePaymentMethodEnum';
 import { SalePaymentDetail } from '../SalePaymentDetail';
+import { SalePayment } from '../SalePayment';
+import { IsSalePaymentList } from '../../validators/IsSalePaymentList';
 
 /**
  * POST /wizard/sessions/:id/payment — registra el cobro de contado (idempotente por sesión). Regla
@@ -9,18 +11,27 @@ import { SalePaymentDetail } from '../SalePaymentDetail';
  * (D11) ANTES del registro; el folio no viaja en el body (lo posee el server). SureKeep Fase 2 — pista Retail.
  */
 export class RegisterPaymentRequest {
+  /** @deprecated Usa `payments`; obligatorio solo si `payments` no viene. */
   @Expose()
+  @ValidateIf((o: { payments?: unknown; method?: unknown }) => o.payments == null || o.method !== undefined)
   @IsEnum(SalePaymentMethodEnum)
-  method!: SalePaymentMethodEnum;
+  method?: SalePaymentMethodEnum;
 
   @Expose()
   @IsInt()
   @Min(0)
   amountCents!: number;
 
+  /** @deprecated Usa el comprobante de cada elemento de `payments`. */
   @Expose()
   @IsOptional()
   @Type(() => SalePaymentDetail)
   @ValidateNested()
   detail?: SalePaymentDetail;
+
+  /** Pagos del cobro (1 a 3); si viene, manda sobre `method` y `detail`. */
+  @Expose()
+  @IsOptional()
+  @IsSalePaymentList()
+  payments?: SalePayment[];
 }

package/src/retailWizard/events/RetailPromotionInboundMessage.ts

@@ -174,11 +174,17 @@ export class RetailPromotionInboundMessage {
     @IsEnum(SaleTypeEnum)
     saleType?: SaleTypeEnum;
 
-    /** Medio de cobro, solo en contado. */
+    /** @deprecated Usa `paymentMethods`. Medio de cobro, solo en contado. */
     @IsOptional()
     @IsEnum(SalePaymentMethodEnum)
     paymentMethod?: SalePaymentMethodEnum | null;
 
+    /** Medios con que se cobró, uno por pago; solo en contado. */
+    @IsOptional()
+    @IsArray()
+    @IsEnum(SalePaymentMethodEnum, { each: true })
+    paymentMethods?: SalePaymentMethodEnum[] | null;
+
     /** Financiera externa, solo en `EXTERNAL_REFERRAL`. */
     @IsOptional()
     @IsEnum(ExternalProviderEnum)

package/src/retailWizard/index.ts

@@ -45,6 +45,11 @@ export * from './dtos/WizardProduct';
 export * from './dtos/WizardWelcome';
 export * from './dtos/WizardCreditPromotionBonus';
 export * from './dtos/SalePaymentDetail';
+export * from './dtos/SalePayment';
+export * from './validators/IsSalePaymentList';
+export * from './validators/OnlyForPaymentMethodConstraint';
+export * from './validators/PaymentsHaveSingleUseMethodsConstraint';
+export * from './validators/PaymentsMatchAmountCentsConstraint';
 export * from './dtos/ProspectNewCustomer';
 export * from './dtos/WizardBeneficiary';
 export * from './dtos/WizardLoan';

package/src/retailWizard/validators/IsSalePaymentList.ts

@@ -0,0 +1,20 @@
+import { Type } from 'class-transformer';
+import { ArrayMaxSize, ArrayMinSize, IsArray, Validate, ValidateNested } from 'class-validator';
+import { MAX_SALE_PAYMENTS } from '../constants/retailWizardValidation';
+import { SalePayment } from '../dtos/SalePayment';
+import { PaymentsHaveSingleUseMethodsConstraint } from './PaymentsHaveSingleUseMethodsConstraint';
+import { PaymentsMatchAmountCentsConstraint } from './PaymentsMatchAmountCentsConstraint';
+
+/** Reglas de `payments`: 1 a 3 pagos válidos, efectivo y SPEI una vez, y la suma igual a `amountCents`. */
+export function IsSalePaymentList(): PropertyDecorator {
+    const decorators: PropertyDecorator[] = [
+        IsArray(),
+        ArrayMinSize(1),
+        ArrayMaxSize(MAX_SALE_PAYMENTS),
+        ValidateNested({ each: true }),
+        Type(() => SalePayment),
+        Validate(PaymentsHaveSingleUseMethodsConstraint),
+        Validate(PaymentsMatchAmountCentsConstraint),
+    ];
+    return (target, propertyKey) => decorators.forEach((decorate) => decorate(target, propertyKey));
+}

package/src/retailWizard/validators/OnlyForPaymentMethodConstraint.ts

@@ -0,0 +1,18 @@
+import {
+    ValidatorConstraint,
+    type ValidationArguments,
+    type ValidatorConstraintInterface,
+} from 'class-validator';
+
+/** Un campo de comprobante con valor solo se acepta en el medio de pago al que pertenece. */
+@ValidatorConstraint({ name: 'onlyForPaymentMethod', async: false })
+export class OnlyForPaymentMethodConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        if (value == null) return true;
+        return (args.object as { method?: unknown }).method === args.constraints[0];
+    }
+
+    defaultMessage(args: ValidationArguments): string {
+        return `${args.property} solo aplica a pagos ${args.constraints[0]}`;
+    }
+}

package/src/retailWizard/validators/PaymentsHaveSingleUseMethodsConstraint.ts

@@ -0,0 +1,20 @@
+import {
+    ValidatorConstraint,
+    type ValidationArguments,
+    type ValidatorConstraintInterface,
+} from 'class-validator';
+import { SINGLE_USE_PAYMENT_METHODS } from '../constants/retailWizardValidation';
+
+/** Efectivo y SPEI aparecen a lo más una vez en `payments`; la tarjeta se puede repetir. */
+@ValidatorConstraint({ name: 'paymentsHaveSingleUseMethods', async: false })
+export class PaymentsHaveSingleUseMethodsConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, _args: ValidationArguments): boolean {
+        if (!Array.isArray(value)) return true;
+        const methods = value.map((p) => (p as { method?: unknown } | null)?.method);
+        return SINGLE_USE_PAYMENT_METHODS.every((m) => methods.filter((x) => x === m).length <= 1);
+    }
+
+    defaultMessage(): string {
+        return `payments admite a lo más un pago de cada medio ${SINGLE_USE_PAYMENT_METHODS.join(' y ')}`;
+    }
+}

package/src/retailWizard/validators/PaymentsMatchAmountCentsConstraint.ts

@@ -0,0 +1,21 @@
+import {
+    ValidatorConstraint,
+    type ValidationArguments,
+    type ValidatorConstraintInterface,
+} from 'class-validator';
+
+/** La suma de `payments[].amountCents` es el `amountCents` del cobro. */
+@ValidatorConstraint({ name: 'paymentsMatchAmountCents', async: false })
+export class PaymentsMatchAmountCentsConstraint implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        const total = (args.object as { amountCents?: unknown }).amountCents;
+        if (!Array.isArray(value) || !Number.isInteger(total)) return true;
+        const amounts = value.map((p) => (p as { amountCents?: unknown } | null)?.amountCents);
+        if (!amounts.every((a) => Number.isInteger(a))) return true;
+        return (amounts as number[]).reduce((sum, a) => sum + a, 0) === total;
+    }
+
+    defaultMessage(): string {
+        return 'la suma de payments[].amountCents debe ser amountCents';
+    }
+}