@fiado/type-kit 3.602.0 → 3.604.0

package/bin/retailIntegration/models/RetailSystemSale.js

@@ -9,13 +9,16 @@ 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.RetailSystemSale = exports.RetailSystemSaleLine = exports.RetailSystemSaleComponent = exports.RetailSystemSaleCustomer = void 0;
+exports.RetailSystemSale = exports.RetailSystemSaleLine = exports.RetailSystemSaleComponent = exports.RetailSystemSalePayment = exports.RetailSystemSaleCredit = exports.RetailSystemSaleCustomer = void 0;
 const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
 const retailIntegrationLimits_1 = require("../constants/retailIntegrationLimits");
 const enums_1 = require("../enums");
+const IsCalendarDate_1 = require("../validators/IsCalendarDate");
 const IsIsoDateTimeWithZone_1 = require("../validators/IsIsoDateTimeWithZone");
 const payloadValidators_1 = require("../validators/payloadValidators");
+const saleValidators_1 = require("../validators/saleValidators");
+const { CARD, WIRE } = enums_1.RetailPaymentMethodEnum;
 class RetailSystemSaleCustomer {
 }
 exports.RetailSystemSaleCustomer = RetailSystemSaleCustomer;
@@ -41,9 +44,70 @@ __decorate([
 ], RetailSystemSaleCustomer.prototype, "maternalLastName", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(/\S/),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_CUSTOMER_PHONE_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSaleCustomer.prototype, "phone", void 0);
+/** Condiciones del crédito; todas obligatorias cuando `credit` no es `null`. */
+class RetailSystemSaleCredit {
+}
+exports.RetailSystemSaleCredit = RetailSystemSaleCredit;
+__decorate([
+    (0, class_validator_1.IsIn)(Object.values(enums_1.RetailPaymentFrequencyEnum)),
+    __metadata("design:type", String)
+], RetailSystemSaleCredit.prototype, "paymentFrequency", void 0);
+__decorate([
+    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.Min)(1),
+    __metadata("design:type", Number)
+], RetailSystemSaleCredit.prototype, "installments", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
+    __metadata("design:type", String)
+], RetailSystemSaleCredit.prototype, "installmentAmount", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
+    __metadata("design:type", String)
+], RetailSystemSaleCredit.prototype, "downPayment", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
+    __metadata("design:type", String)
+], RetailSystemSaleCredit.prototype, "totalToPay", void 0);
+__decorate([
+    (0, class_validator_1.Validate)(IsCalendarDate_1.IsCalendarDate),
+    __metadata("design:type", String)
+], RetailSystemSaleCredit.prototype, "firstPaymentDate", void 0);
+/** Un medio de pago de `amountPaid`; las seis llaves van siempre, en `null` las que no aplican. */
+class RetailSystemSalePayment {
+}
+exports.RetailSystemSalePayment = RetailSystemSalePayment;
+__decorate([
+    (0, class_validator_1.IsIn)(Object.values(enums_1.RetailPaymentMethodEnum)),
+    __metadata("design:type", String)
+], RetailSystemSalePayment.prototype, "method", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_POSITIVE_DECIMAL_PATTERN),
+    __metadata("design:type", String)
+], RetailSystemSalePayment.prototype, "amount", void 0);
+__decorate([
+    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [CARD, retailIntegrationLimits_1.RETAIL_CARD_LAST4_PATTERN]),
+    __metadata("design:type", String)
+], RetailSystemSalePayment.prototype, "cardLast4", void 0);
+__decorate([
+    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [CARD, retailIntegrationLimits_1.RETAIL_SALE_ID_TEXT_PATTERN]),
+    __metadata("design:type", String)
+], RetailSystemSalePayment.prototype, "authCode", void 0);
+__decorate([
+    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [WIRE, retailIntegrationLimits_1.RETAIL_SPEI_TRACKING_KEY_PATTERN]),
+    __metadata("design:type", String)
+], RetailSystemSalePayment.prototype, "speiTrackingKey", void 0);
+__decorate([
+    (0, class_validator_1.Validate)(saleValidators_1.MatchesForPaymentMethod, [WIRE, retailIntegrationLimits_1.RETAIL_CLABE_PATTERN, true]),
+    __metadata("design:type", String)
+], RetailSystemSalePayment.prototype, "senderClabe", void 0);
 class RetailSystemSaleComponent {
 }
 exports.RetailSystemSaleComponent = RetailSystemSaleComponent;
@@ -83,12 +147,12 @@ __decorate([
 ], RetailSystemSaleLine.prototype, "qty", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSaleLine.prototype, "basePrice", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSaleLine.prototype, "discount", void 0);
 __decorate([
@@ -97,7 +161,7 @@ __decorate([
 ], RetailSystemSaleLine.prototype, "paymentType", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSaleLine.prototype, "financedAmount", void 0);
 __decorate([
@@ -105,6 +169,10 @@ __decorate([
     (0, class_validator_1.IsIn)(Object.values(enums_1.RetailSaleLineRoleEnum)),
     __metadata("design:type", String)
 ], RetailSystemSaleLine.prototype, "role", void 0);
+__decorate([
+    (0, class_validator_1.Validate)(saleValidators_1.PromotionIdMatchesRole),
+    __metadata("design:type", String)
+], RetailSystemSaleLine.prototype, "promotionId", void 0);
 __decorate([
     (0, class_validator_1.IsArray)(),
     (0, class_validator_1.ValidateNested)({ each: true }),
@@ -145,6 +213,7 @@ __decorate([
 ], RetailSystemSale.prototype, "saleType", void 0);
 __decorate([
     (0, class_validator_1.IsIn)(Object.values(enums_1.RetailSaleFinancierEnum)),
+    (0, class_validator_1.Validate)(saleValidators_1.CreditMatchesFinancier),
     __metadata("design:type", String)
 ], RetailSystemSale.prototype, "financier", void 0);
 __decorate([
@@ -153,6 +222,13 @@ __decorate([
     (0, class_validator_1.Matches)(/\S/),
     __metadata("design:type", String)
 ], RetailSystemSale.prototype, "creditId", void 0);
+__decorate([
+    (0, class_validator_1.ValidateIf)(payloadValidators_1.isNullOrValidated),
+    (0, class_validator_1.IsObject)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => RetailSystemSaleCredit),
+    __metadata("design:type", RetailSystemSaleCredit)
+], RetailSystemSale.prototype, "credit", void 0);
 __decorate([
     (0, class_validator_1.IsIn)(Object.values(enums_1.RetailCurrencyEnum)),
     __metadata("design:type", String)
@@ -165,19 +241,21 @@ __decorate([
 ], RetailSystemSale.prototype, "customer", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSale.prototype, "equipmentPrice", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
-    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_DECIMAL_PATTERN),
+    (0, class_validator_1.Matches)(retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN),
     __metadata("design:type", String)
 ], RetailSystemSale.prototype, "amountPaid", void 0);
 __decorate([
-    (0, class_validator_1.ValidateIf)(payloadValidators_1.isNullOrValidated),
-    (0, class_validator_1.IsIn)(Object.values(enums_1.RetailPaymentMethodEnum)),
-    __metadata("design:type", String)
-], RetailSystemSale.prototype, "paymentMethod", void 0);
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.ValidateNested)({ each: true }),
+    (0, class_transformer_1.Type)(() => RetailSystemSalePayment),
+    (0, class_validator_1.Validate)(saleValidators_1.PaymentsMatchAmountPaid),
+    __metadata("design:type", Array)
+], RetailSystemSale.prototype, "payments", void 0);
 __decorate([
     (0, class_validator_1.IsArray)(),
     (0, class_validator_1.ArrayNotEmpty)(),

package/bin/retailIntegration/validators/IsCalendarDate.d.ts

@@ -0,0 +1,6 @@
+import { ValidatorConstraintInterface } from 'class-validator';
+/** Acepta una fecha `YYYY-MM-DD` que exista en el calendario. */
+export declare class IsCalendarDate implements ValidatorConstraintInterface {
+    validate(value: unknown): boolean;
+    defaultMessage(): string;
+}

package/bin/retailIntegration/validators/IsCalendarDate.js

@@ -0,0 +1,25 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IsCalendarDate = void 0;
+const class_validator_1 = require("class-validator");
+const calendarDate_1 = require("./calendarDate");
+const CALENDAR_DATE = /^\d{4}-\d{2}-\d{2}$/;
+/** Acepta una fecha `YYYY-MM-DD` que exista en el calendario. */
+let IsCalendarDate = class IsCalendarDate {
+    validate(value) {
+        return typeof value === 'string' && CALENDAR_DATE.test(value) && (0, calendarDate_1.isRealCalendarDate)(value);
+    }
+    defaultMessage() {
+        return 'debe ser una fecha YYYY-MM-DD, por ejemplo 2026-08-21';
+    }
+};
+exports.IsCalendarDate = IsCalendarDate;
+exports.IsCalendarDate = IsCalendarDate = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'isCalendarDate', async: false })
+], IsCalendarDate);

package/bin/retailIntegration/validators/IsIsoDateTimeWithZone.js

@@ -8,16 +8,12 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.IsIsoDateTimeWithZone = void 0;
 const class_validator_1 = require("class-validator");
+const calendarDate_1 = require("./calendarDate");
 const ISO_DATE_TIME_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
-/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero. */
-function isRealCalendarDate(value) {
-    const [year, month, day] = value.slice(0, 10).split('-').map(Number);
-    return !Number.isNaN(Date.parse(value)) && new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
-}
 /** Acepta fecha y hora ISO-8601 con segundos y zona; sin zona se rechaza, como dice la doc. */
 let IsIsoDateTimeWithZone = class IsIsoDateTimeWithZone {
     validate(value) {
-        return typeof value === 'string' && ISO_DATE_TIME_WITH_ZONE.test(value) && isRealCalendarDate(value);
+        return typeof value === 'string' && ISO_DATE_TIME_WITH_ZONE.test(value) && (0, calendarDate_1.isRealCalendarDate)(value);
     }
     defaultMessage() {
         return 'debe ser fecha y hora ISO-8601 con zona, por ejemplo 2026-08-17T20:32:05Z';

package/bin/retailIntegration/validators/calendarDate.d.ts

@@ -0,0 +1,2 @@
+/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero; lee los primeros 10 caracteres. */
+export declare function isRealCalendarDate(value: string): boolean;

package/bin/retailIntegration/validators/calendarDate.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRealCalendarDate = isRealCalendarDate;
+/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero; lee los primeros 10 caracteres. */
+function isRealCalendarDate(value) {
+    const [year, month, day] = value.slice(0, 10).split('-').map(Number);
+    return !Number.isNaN(Date.parse(value)) && new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
+}

package/bin/retailIntegration/validators/saleValidators.d.ts

@@ -0,0 +1,26 @@
+import { ValidationArguments, ValidatorConstraintInterface } from 'class-validator';
+/** Campo de un pago que solo aplica a un medio: con ese medio cumple el patrón; con los demás es `null`. */
+export declare class MatchesForPaymentMethod implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(args: ValidationArguments): string;
+}
+/** La suma de `payments[].amount` es `amountPaid`; con `amountPaid` en `"0.00"` el arreglo va vacío. */
+export declare class PaymentsMatchAmountPaid implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}
+/** `credit` y `creditId`: obligatorios con `SUREKEEP` y `null` en contado. */
+export declare class CreditMatchesFinancier implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}
+/** `promotionId`: texto o `null`, nunca omitido; un regalo siempre lo trae. */
+export declare class PromotionIdMatchesRole implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}
+/** Un dañado con `identifier` es una sola pieza: `qty` debe ser 1. */
+export declare class QtyMatchesIdentifier implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}

package/bin/retailIntegration/validators/saleValidators.js

@@ -0,0 +1,100 @@
+"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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QtyMatchesIdentifier = exports.PromotionIdMatchesRole = exports.CreditMatchesFinancier = exports.PaymentsMatchAmountPaid = exports.MatchesForPaymentMethod = void 0;
+const class_validator_1 = require("class-validator");
+const retailIntegrationLimits_1 = require("../constants/retailIntegrationLimits");
+const enums_1 = require("../enums");
+function decimalToCents(value) {
+    return Number(value.replace('.', ''));
+}
+/** Campo de un pago que solo aplica a un medio: con ese medio cumple el patrón; con los demás es `null`. */
+let MatchesForPaymentMethod = class MatchesForPaymentMethod {
+    validate(value, args) {
+        const [method, pattern, nullable] = args.constraints;
+        if (args.object.method !== method)
+            return value === null;
+        if (value === null)
+            return nullable === true;
+        return typeof value === 'string' && pattern.test(value);
+    }
+    defaultMessage(args) {
+        return `${args.property} es obligatorio y válido en ${args.constraints[0]} y null en los demás medios`;
+    }
+};
+exports.MatchesForPaymentMethod = MatchesForPaymentMethod;
+exports.MatchesForPaymentMethod = MatchesForPaymentMethod = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'matchesForPaymentMethod', async: false })
+], MatchesForPaymentMethod);
+/** La suma de `payments[].amount` es `amountPaid`; con `amountPaid` en `"0.00"` el arreglo va vacío. */
+let PaymentsMatchAmountPaid = class PaymentsMatchAmountPaid {
+    validate(value, args) {
+        const amountPaid = args.object.amountPaid;
+        if (!Array.isArray(value) || typeof amountPaid !== 'string' || !retailIntegrationLimits_1.RETAIL_SALE_DECIMAL_PATTERN.test(amountPaid))
+            return true;
+        const amounts = value.map((p) => p?.amount);
+        if (!amounts.every((a) => typeof a === 'string' && retailIntegrationLimits_1.RETAIL_SALE_POSITIVE_DECIMAL_PATTERN.test(a)))
+            return true;
+        const total = amounts.reduce((sum, a) => sum + decimalToCents(a), 0);
+        return total === decimalToCents(amountPaid);
+    }
+    defaultMessage() {
+        return 'la suma de payments[].amount debe ser amountPaid; [] solo si amountPaid es 0.00';
+    }
+};
+exports.PaymentsMatchAmountPaid = PaymentsMatchAmountPaid;
+exports.PaymentsMatchAmountPaid = PaymentsMatchAmountPaid = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'paymentsMatchAmountPaid', async: false })
+], PaymentsMatchAmountPaid);
+/** `credit` y `creditId`: obligatorios con `SUREKEEP` y `null` en contado. */
+let CreditMatchesFinancier = class CreditMatchesFinancier {
+    validate(value, args) {
+        const { saleType, credit, creditId } = args.object;
+        if (value === enums_1.RetailSaleFinancierEnum.SUREKEEP)
+            return credit !== null && creditId !== null;
+        if (value === enums_1.RetailSaleFinancierEnum.NONE || saleType === enums_1.RetailSaleTypeEnum.CASH)
+            return credit == null && creditId == null;
+        return true;
+    }
+    defaultMessage() {
+        return 'credit y creditId son obligatorios con SUREKEEP y null en contado';
+    }
+};
+exports.CreditMatchesFinancier = CreditMatchesFinancier;
+exports.CreditMatchesFinancier = CreditMatchesFinancier = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'creditMatchesFinancier', async: false })
+], CreditMatchesFinancier);
+/** `promotionId`: texto o `null`, nunca omitido; un regalo siempre lo trae. */
+let PromotionIdMatchesRole = class PromotionIdMatchesRole {
+    validate(value, args) {
+        if (value === null)
+            return args.object.role !== enums_1.RetailSaleLineRoleEnum.GIFT;
+        return typeof value === 'string' && retailIntegrationLimits_1.RETAIL_SALE_ID_TEXT_PATTERN.test(value);
+    }
+    defaultMessage() {
+        return 'promotionId es texto de 1 a 64 o null, y obligatorio con role GIFT';
+    }
+};
+exports.PromotionIdMatchesRole = PromotionIdMatchesRole;
+exports.PromotionIdMatchesRole = PromotionIdMatchesRole = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'promotionIdMatchesRole', async: false })
+], PromotionIdMatchesRole);
+/** Un dañado con `identifier` es una sola pieza: `qty` debe ser 1. */
+let QtyMatchesIdentifier = class QtyMatchesIdentifier {
+    validate(value, args) {
+        const identifier = args.object.identifier;
+        return typeof identifier !== 'string' || value === 1;
+    }
+    defaultMessage() {
+        return 'qty debe ser 1 cuando viene identifier';
+    }
+};
+exports.QtyMatchesIdentifier = QtyMatchesIdentifier;
+exports.QtyMatchesIdentifier = QtyMatchesIdentifier = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'qtyMatchesIdentifier', async: false })
+], QtyMatchesIdentifier);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/type-kit",
-  "version": "3.602.0",
+  "version": "3.604.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

package/src/retailIntegration/constants/retailIntegrationLimits.ts

@@ -66,3 +66,27 @@ export const RETAIL_LINE_INDEX_MAX = 999;
 
 /** Rango máximo de `GET /inventory/movements`: 7 días en milisegundos. */
 export const RETAIL_MOVEMENTS_RANGE_MAX_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Decimal de la venta y la cancelación: hasta 12 enteros y dos decimales, nunca negativo. */
+export const RETAIL_SALE_DECIMAL_PATTERN = /^\d{1,12}\.\d{2}$/;
+
+/** Decimal de la venta mayor que cero, como `payments[].amount`. */
+export const RETAIL_SALE_POSITIVE_DECIMAL_PATTERN = /^(?=.*[1-9])\d{1,12}\.\d{2}$/;
+
+/** Texto libre corto de la venta, como `authCode` y `promotionId`: no vacío y de a lo más 64. */
+export const RETAIL_SALE_ID_TEXT_PATTERN = /^(?=.*\S).{1,64}$/;
+
+/** Últimos 4 dígitos de la tarjeta en un pago `CARD`. */
+export const RETAIL_CARD_LAST4_PATTERN = /^\d{4}$/;
+
+/** Clave de rastreo SPEI de un pago `WIRE`: alfanumérica de 1 a 30, como la define Banxico. */
+export const RETAIL_SPEI_TRACKING_KEY_PATTERN = /^[A-Za-z0-9]{1,30}$/;
+
+/** CLABE de la cuenta que envió un pago `WIRE`: 18 dígitos. */
+export const RETAIL_CLABE_PATTERN = /^\d{18}$/;
+
+/** Tope del motivo de cancelación de una venta. */
+export const RETAIL_CANCEL_REASON_MAX_LENGTH = 200;
+
+/** Teléfono del cliente en la venta: 10 dígitos. */
+export const RETAIL_CUSTOMER_PHONE_PATTERN = /^\d{10}$/;

package/src/retailIntegration/dtos/CancelRetailSaleRequest.ts

@@ -1,9 +1,21 @@
-import { IsString, Matches, Validate } from 'class-validator';
+import { Type } from 'class-transformer';
+import { IsArray, IsInt, IsString, Matches, MaxLength, Min, Validate, ValidateIf, ValidateNested } from 'class-validator';
+import { RETAIL_CANCEL_REASON_MAX_LENGTH, RETAIL_SHORT_TEXT_MAX_LENGTH, RETAIL_SKU_PATTERN } from '../constants/retailIntegrationLimits';
 import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
+import { isNullOrValidated } from '../validators/payloadValidators';
+import { QtyMatchesIdentifier } from '../validators/saleValidators';
+
+/** Lo que regresa dañado al cancelar; `identifier` en `null` si el producto es `QUANTITY`. */
+export class RetailSystemDamagedItem {
+    @IsString() @Matches(RETAIL_SKU_PATTERN) sku!: string;
+    @ValidateIf(isNullOrValidated) @IsString() @Matches(/\S/) @MaxLength(RETAIL_SHORT_TEXT_MAX_LENGTH) identifier!: string | null;
+    @IsInt() @Min(1) @Validate(QtyMatchesIdentifier) qty!: number;
+}
 
 /** Cuerpo de `POST /private/retail/sales/cancel`; el `saleId` es el mismo del registro. */
 export class CancelRetailSaleRequest {
     @IsString() @Matches(/\S/) saleId!: string;
     @Validate(IsIsoDateTimeWithZone) cancelledAt!: string;
-    @IsString() @Matches(/\S/) reason!: string;
+    @IsString() @Matches(/\S/) @MaxLength(RETAIL_CANCEL_REASON_MAX_LENGTH) reason!: string;
+    @IsArray() @ValidateNested({ each: true }) @Type(() => RetailSystemDamagedItem) damaged!: RetailSystemDamagedItem[];
 }

package/src/retailIntegration/dtos/RetailOutboundResponses.ts

@@ -1,3 +1,4 @@
+import { RetailEventRejectCodeEnum } from '../enums';
 import { RetailInventoryMeta, RetailPageMeta } from '../models/RetailPageMeta';
 import { RetailSystemInventoryMovement, RetailSystemPiece, RetailSystemStock } from '../models/RetailSystemInventory';
 import { RetailSystemProduct } from '../models/RetailSystemProduct';
@@ -23,10 +24,19 @@ export interface GetRetailInventoryResponse {
     meta: RetailInventoryMeta;
 }
 
-/** `data` de `GET /private/retail/inventory/movements`. */
+/** Movimiento de la página que no cumple el sobre del webhook; catalog lo salta y lo cuenta. */
+export interface InvalidRetailInventoryMovement {
+    index: number;
+    eventId?: string;
+    code: RetailEventRejectCodeEnum.INVALID_PAYLOAD;
+    invalidPaths: string[];
+}
+
+/** `data` de `GET /private/retail/inventory/movements`; `invalidItems` lista los movimientos descartados. */
 export interface ListRetailInventoryMovementsResponse {
     items: RetailSystemInventoryMovement[];
     meta: RetailPageMeta;
+    invalidItems?: InvalidRetailInventoryMovement[];
 }
 
 /** `data` de `GET /private/retail/users`. */

package/src/retailIntegration/enums/RetailPaymentFrequencyEnum.ts

@@ -0,0 +1,6 @@
+/** Cada cuánto paga el cliente en `credit.paymentFrequency`. */
+export enum RetailPaymentFrequencyEnum {
+    WEEKLY = 'WEEKLY',
+    BIWEEKLY = 'BIWEEKLY',
+    MONTHLY = 'MONTHLY',
+}

package/src/retailIntegration/enums/RetailPaymentMethodEnum.ts

@@ -1,6 +1,7 @@
-/** Método de pago de la venta. */
+/** Medio de pago de `payments[].method` en la venta. */
 export enum RetailPaymentMethodEnum {
     CASH = 'CASH',
     CARD = 'CARD',
-    SPEI = 'SPEI',
+    WIRE = 'WIRE',
+    FIADO = 'FIADO',
 }

package/src/retailIntegration/enums/index.ts

@@ -18,6 +18,7 @@ export * from './RetailUserAccessStatusEnum';
 export * from './RetailSaleTypeEnum';
 export * from './RetailSaleFinancierEnum';
 export * from './RetailPaymentMethodEnum';
+export * from './RetailPaymentFrequencyEnum';
 export * from './RetailLinePaymentTypeEnum';
 export * from './RetailSaleLineRoleEnum';
 export * from './RetailEventRejectCodeEnum';

package/src/retailIntegration/index.ts

@@ -3,6 +3,8 @@ export * from './constants/retailIntegrationErrorHttpStatus';
 export * from './enums';
 export * from './validators/IsIsoDateTimeWithZone';
 export * from './validators/IsMovementsRangeValid';
+export * from './validators/IsCalendarDate';
+export * from './validators/saleValidators';
 export * from './dtos/RetailEventEnvelope';
 export * from './dtos/ReceiveStoreEventRequest';
 export * from './dtos/ReceiveRetailUserEventRequest';

package/src/retailIntegration/models/RetailSystemSale.ts

@@ -1,23 +1,66 @@
 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 {
+    RETAIL_CARD_LAST4_PATTERN,
+    RETAIL_CLABE_PATTERN,
+    RETAIL_CUSTOMER_PHONE_PATTERN,
+    RETAIL_ENTITY_ID_PATTERN,
+    RETAIL_SALE_DECIMAL_PATTERN,
+    RETAIL_SALE_ID_TEXT_PATTERN,
+    RETAIL_SALE_POSITIVE_DECIMAL_PATTERN,
+    RETAIL_SKU_PATTERN,
+    RETAIL_SPEI_TRACKING_KEY_PATTERN,
+} from '../constants/retailIntegrationLimits';
+import {
+    RetailCurrencyEnum,
+    RetailLinePaymentTypeEnum,
+    RetailPaymentFrequencyEnum,
+    RetailPaymentMethodEnum,
+    RetailSaleFinancierEnum,
+    RetailSaleLineRoleEnum,
+    RetailSaleTypeEnum,
+} from '../enums';
+import { IsCalendarDate } from '../validators/IsCalendarDate';
 import { IsIsoDateTimeWithZone } from '../validators/IsIsoDateTimeWithZone';
 import { HasUniqueKeys, isNullOrValidated } from '../validators/payloadValidators';
+import { CreditMatchesFinancier, MatchesForPaymentMethod, PaymentsMatchAmountPaid, PromotionIdMatchesRole } from '../validators/saleValidators';
 import { RetailCurrency } from './RetailSystemProduct';
 
 export type RetailSaleType = `${RetailSaleTypeEnum}`;
 export type RetailSaleFinancier = `${RetailSaleFinancierEnum}`;
 export type RetailPaymentMethod = `${RetailPaymentMethodEnum}`;
+export type RetailPaymentFrequency = `${RetailPaymentFrequencyEnum}`;
 export type RetailLinePaymentType = `${RetailLinePaymentTypeEnum}`;
 export type RetailSaleLineRole = `${RetailSaleLineRoleEnum}`;
 
+const { CARD, WIRE } = RetailPaymentMethodEnum;
+
 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;
+    @IsString() @Matches(RETAIL_CUSTOMER_PHONE_PATTERN) phone!: string;
+}
+
+/** Condiciones del crédito; todas obligatorias cuando `credit` no es `null`. */
+export class RetailSystemSaleCredit {
+    @IsIn(Object.values(RetailPaymentFrequencyEnum)) paymentFrequency!: RetailPaymentFrequency;
+    @IsInt() @Min(1) installments!: number;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) installmentAmount!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) downPayment!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) totalToPay!: string;
+    @Validate(IsCalendarDate) firstPaymentDate!: string;
+}
+
+/** Un medio de pago de `amountPaid`; las seis llaves van siempre, en `null` las que no aplican. */
+export class RetailSystemSalePayment {
+    @IsIn(Object.values(RetailPaymentMethodEnum)) method!: RetailPaymentMethod;
+    @IsString() @Matches(RETAIL_SALE_POSITIVE_DECIMAL_PATTERN) amount!: string;
+    @Validate(MatchesForPaymentMethod, [CARD, RETAIL_CARD_LAST4_PATTERN]) cardLast4!: string | null;
+    @Validate(MatchesForPaymentMethod, [CARD, RETAIL_SALE_ID_TEXT_PATTERN]) authCode!: string | null;
+    @Validate(MatchesForPaymentMethod, [WIRE, RETAIL_SPEI_TRACKING_KEY_PATTERN]) speiTrackingKey!: string | null;
+    @Validate(MatchesForPaymentMethod, [WIRE, RETAIL_CLABE_PATTERN, true]) senderClabe!: string | null;
 }
 
 export class RetailSystemSaleComponent {
@@ -30,11 +73,12 @@ 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;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) basePrice!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) discount!: string;
     @IsIn(Object.values(RetailLinePaymentTypeEnum)) paymentType!: RetailLinePaymentType;
-    @IsString() @Matches(RETAIL_DECIMAL_PATTERN) financedAmount!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) financedAmount!: string;
     @ValidateIf(isNullOrValidated) @IsIn(Object.values(RetailSaleLineRoleEnum)) role!: RetailSaleLineRole | null;
+    @Validate(PromotionIdMatchesRole) promotionId!: string | null;
     @IsArray() @ValidateNested({ each: true }) @Type(() => RetailSystemSaleComponent) components!: RetailSystemSaleComponent[];
 }
 
@@ -46,13 +90,16 @@ export class RetailSystemSale {
     @IsString() @Matches(RETAIL_ENTITY_ID_PATTERN) sellerRetailUserId!: string;
     @Validate(IsIsoDateTimeWithZone) soldAt!: string;
     @IsIn(Object.values(RetailSaleTypeEnum)) saleType!: RetailSaleType;
-    @IsIn(Object.values(RetailSaleFinancierEnum)) financier!: RetailSaleFinancier;
+    @IsIn(Object.values(RetailSaleFinancierEnum)) @Validate(CreditMatchesFinancier) financier!: RetailSaleFinancier;
     @ValidateIf(isNullOrValidated) @IsString() @Matches(/\S/) creditId!: string | null;
+    @ValidateIf(isNullOrValidated) @IsObject() @ValidateNested() @Type(() => RetailSystemSaleCredit) credit!: RetailSystemSaleCredit | 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;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) equipmentPrice!: string;
+    @IsString() @Matches(RETAIL_SALE_DECIMAL_PATTERN) amountPaid!: string;
+
+    @IsArray() @ValidateNested({ each: true }) @Type(() => RetailSystemSalePayment) @Validate(PaymentsMatchAmountPaid)
+    payments!: RetailSystemSalePayment[];
 
     @IsArray() @ArrayNotEmpty() @ValidateNested({ each: true }) @Type(() => RetailSystemSaleLine) @Validate(HasUniqueKeys, ['lineId'])
     lines!: RetailSystemSaleLine[];

package/src/retailIntegration/validators/IsCalendarDate.ts

@@ -0,0 +1,16 @@
+import { ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+import { isRealCalendarDate } from './calendarDate';
+
+const CALENDAR_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+/** Acepta una fecha `YYYY-MM-DD` que exista en el calendario. */
+@ValidatorConstraint({ name: 'isCalendarDate', async: false })
+export class IsCalendarDate implements ValidatorConstraintInterface {
+    validate(value: unknown): boolean {
+        return typeof value === 'string' && CALENDAR_DATE.test(value) && isRealCalendarDate(value);
+    }
+
+    defaultMessage(): string {
+        return 'debe ser una fecha YYYY-MM-DD, por ejemplo 2026-08-21';
+    }
+}

package/src/retailIntegration/validators/IsIsoDateTimeWithZone.ts

@@ -1,13 +1,8 @@
 import { ValidatorConstraint, ValidatorConstraintInterface } from 'class-validator';
+import { isRealCalendarDate } from './calendarDate';
 
 const ISO_DATE_TIME_WITH_ZONE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
 
-/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero. */
-function isRealCalendarDate(value: string): boolean {
-    const [year, month, day] = value.slice(0, 10).split('-').map(Number);
-    return !Number.isNaN(Date.parse(value)) && new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
-}
-
 /** Acepta fecha y hora ISO-8601 con segundos y zona; sin zona se rechaza, como dice la doc. */
 @ValidatorConstraint({ name: 'isIsoDateTimeWithZone', async: false })
 export class IsIsoDateTimeWithZone implements ValidatorConstraintInterface {

package/src/retailIntegration/validators/calendarDate.ts

@@ -0,0 +1,5 @@
+/** Descarta fechas que `Date` recorre en silencio, como el 31 de febrero; lee los primeros 10 caracteres. */
+export function isRealCalendarDate(value: string): boolean {
+    const [year, month, day] = value.slice(0, 10).split('-').map(Number);
+    return !Number.isNaN(Date.parse(value)) && new Date(Date.UTC(year, month - 1, day)).getUTCDate() === day;
+}