@fiado/type-kit 3.381.0 → 3.383.0

package/bin/collection/dtos/ApplyCollectionResultRequest.d.ts

@@ -1,5 +1,13 @@
 import { CollectionResultStatus } from '../enums/CollectionResultStatus';
 import { MechanismType } from '../enums/MechanismType';
+/**
+ * Resultado de un intento de cobro, tal como el motor se lo entrega al dominio dueño de la deuda.
+ *
+ * Se entrega con reintentos hasta que el dominio la acepta respondiendo `true`. Cualquier otra
+ * respuesta se lee como no entregada y el mismo resultado vuelve más tarde, así que aplicarlo tiene
+ * que ser idempotente: el dominio deduplica por `attemptId`, que identifica ESE intento y no el cobro
+ * entero.
+ */
 export declare class ApplyCollectionResultRequest {
     attemptId: string;
     intentId: string;

package/bin/collection/dtos/ApplyCollectionResultRequest.js

@@ -13,6 +13,14 @@ exports.ApplyCollectionResultRequest = void 0;
 const class_validator_1 = require("class-validator");
 const CollectionResultStatus_1 = require("../enums/CollectionResultStatus");
 const MechanismType_1 = require("../enums/MechanismType");
+/**
+ * Resultado de un intento de cobro, tal como el motor se lo entrega al dominio dueño de la deuda.
+ *
+ * Se entrega con reintentos hasta que el dominio la acepta respondiendo `true`. Cualquier otra
+ * respuesta se lee como no entregada y el mismo resultado vuelve más tarde, así que aplicarlo tiene
+ * que ser idempotente: el dominio deduplica por `attemptId`, que identifica ESE intento y no el cobro
+ * entero.
+ */
 class ApplyCollectionResultRequest {
 }
 exports.ApplyCollectionResultRequest = ApplyCollectionResultRequest;
@@ -41,11 +49,11 @@ __decorate([
     __metadata("design:type", String)
 ], ApplyCollectionResultRequest.prototype, "result", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], ApplyCollectionResultRequest.prototype, "amountCollected", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], ApplyCollectionResultRequest.prototype, "amountReserved", void 0);
 __decorate([

package/bin/collection/dtos/AuthorizeCollectionMovementRequest.d.ts

@@ -1,5 +1,6 @@
 import { MechanismType } from '../enums/MechanismType';
 import { CurrencyId } from '../../currency/enums/CurrencyId';
+import { CollectionPricingDto } from './CollectionPricingDto';
 export declare class AuthorizeCollectionMovementRequest {
     executionId: string;
     directoryId: string;
@@ -10,4 +11,11 @@ export declare class AuthorizeCollectionMovementRequest {
     intentId?: string;
     chargeId?: string;
     holdTxId?: string;
+    /**
+     * Tarifa con la que se registra el cobro. Presente, el movimiento deja además una transacción
+     * Fiado: asiento contable, historial visible para el cliente y comisión declarada. Ausente, el
+     * dinero se mueve igual pero sin ese registro — es el comportamiento anterior, y se conserva para
+     * no romper a quien todavía no manda tarifa.
+     */
+    pricing?: CollectionPricingDto;
 }

package/bin/collection/dtos/AuthorizeCollectionMovementRequest.js

@@ -11,8 +11,10 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthorizeCollectionMovementRequest = void 0;
 const class_validator_1 = require("class-validator");
+const class_transformer_1 = require("class-transformer");
 const MechanismType_1 = require("../enums/MechanismType");
 const CurrencyId_1 = require("../../currency/enums/CurrencyId");
+const CollectionPricingDto_1 = require("./CollectionPricingDto");
 class AuthorizeCollectionMovementRequest {
 }
 exports.AuthorizeCollectionMovementRequest = AuthorizeCollectionMovementRequest;
@@ -33,7 +35,7 @@ __decorate([
     __metadata("design:type", String)
 ], AuthorizeCollectionMovementRequest.prototype, "mechanism", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], AuthorizeCollectionMovementRequest.prototype, "amount", void 0);
 __decorate([
@@ -55,3 +57,9 @@ __decorate([
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
 ], AuthorizeCollectionMovementRequest.prototype, "holdTxId", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => CollectionPricingDto_1.CollectionPricingDto),
+    __metadata("design:type", CollectionPricingDto_1.CollectionPricingDto)
+], AuthorizeCollectionMovementRequest.prototype, "pricing", void 0);

package/bin/collection/dtos/AuthorizeCollectionMovementResponse.d.ts

@@ -1,4 +1,10 @@
 import { CollectionResultStatus } from '../enums/CollectionResultStatus';
+/**
+ * Lo que el procesador responde tras ejecutar un movimiento de cobro.
+ *
+ * `amount` es lo reservado o lo cobrado según el mecanismo, y `holdTxId` sólo viene cuando se reservó:
+ * es con lo que después se captura o se libera la retención.
+ */
 export declare class AuthorizeCollectionMovementResponse {
     status: CollectionResultStatus;
     amount: number;

package/bin/collection/dtos/AuthorizeCollectionMovementResponse.js

@@ -12,6 +12,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuthorizeCollectionMovementResponse = void 0;
 const class_validator_1 = require("class-validator");
 const CollectionResultStatus_1 = require("../enums/CollectionResultStatus");
+/**
+ * Lo que el procesador responde tras ejecutar un movimiento de cobro.
+ *
+ * `amount` es lo reservado o lo cobrado según el mecanismo, y `holdTxId` sólo viene cuando se reservó:
+ * es con lo que después se captura o se libera la retención.
+ */
 class AuthorizeCollectionMovementResponse {
 }
 exports.AuthorizeCollectionMovementResponse = AuthorizeCollectionMovementResponse;
@@ -20,7 +26,7 @@ __decorate([
     __metadata("design:type", String)
 ], AuthorizeCollectionMovementResponse.prototype, "status", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], AuthorizeCollectionMovementResponse.prototype, "amount", void 0);
 __decorate([

package/bin/collection/dtos/CollectRequest.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Cobro inmediato y síncrono, con el importe ya resuelto por el dominio.
+ *
+ * Es para cuando alguien espera la respuesta —un botón, una liquidación anticipada—. La cobranza
+ * recurrente no va por aquí: para eso está el alta, donde el motor se encarga de perseguir el cargo.
+ *
+ * Idempotente por dominio y cargo: repetirlo sobre un cargo ya cobrado devuelve el resultado anterior
+ * sin volver a mover dinero.
+ */
 export declare class CollectRequest {
     directoryId: string;
     tenantId: string;

package/bin/collection/dtos/CollectRequest.js

@@ -11,6 +11,15 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CollectRequest = void 0;
 const class_validator_1 = require("class-validator");
+/**
+ * Cobro inmediato y síncrono, con el importe ya resuelto por el dominio.
+ *
+ * Es para cuando alguien espera la respuesta —un botón, una liquidación anticipada—. La cobranza
+ * recurrente no va por aquí: para eso está el alta, donde el motor se encarga de perseguir el cargo.
+ *
+ * Idempotente por dominio y cargo: repetirlo sobre un cargo ya cobrado devuelve el resultado anterior
+ * sin volver a mover dinero.
+ */
 class CollectRequest {
 }
 exports.CollectRequest = CollectRequest;
@@ -35,6 +44,6 @@ __decorate([
     __metadata("design:type", String)
 ], CollectRequest.prototype, "chargeId", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], CollectRequest.prototype, "amount", void 0);

package/bin/collection/dtos/CollectResponse.d.ts

@@ -1,4 +1,13 @@
 import { CollectionResultStatus } from '../enums/CollectionResultStatus';
+/**
+ * Desenlace de un cobro.
+ *
+ * Lo cobrado y lo reservado van separados porque no son lo mismo: lo primero ya salió de la cuenta y
+ * el dominio debe aplicarlo a su cartera; lo segundo sigue siendo del titular, congelado, esperando
+ * que alguien capture la retención.
+ *
+ * `NONE` no es un fallo: el cargo queda vivo esperando fondos, y el motor lo reintenta solo.
+ */
 export declare class CollectResponse {
     intentId: string;
     status: CollectionResultStatus;

package/bin/collection/dtos/CollectResponse.js

@@ -12,6 +12,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CollectResponse = void 0;
 const class_validator_1 = require("class-validator");
 const CollectionResultStatus_1 = require("../enums/CollectionResultStatus");
+/**
+ * Desenlace de un cobro.
+ *
+ * Lo cobrado y lo reservado van separados porque no son lo mismo: lo primero ya salió de la cuenta y
+ * el dominio debe aplicarlo a su cartera; lo segundo sigue siendo del titular, congelado, esperando
+ * que alguien capture la retención.
+ *
+ * `NONE` no es un fallo: el cargo queda vivo esperando fondos, y el motor lo reintenta solo.
+ */
 class CollectResponse {
 }
 exports.CollectResponse = CollectResponse;
@@ -24,10 +33,10 @@ __decorate([
     __metadata("design:type", String)
 ], CollectResponse.prototype, "status", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], CollectResponse.prototype, "amountReserved", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], CollectResponse.prototype, "amountCollected", void 0);

package/bin/collection/dtos/CollectionAttemptDto.js

@@ -34,7 +34,7 @@ __decorate([
     __metadata("design:type", String)
 ], CollectionAttemptDto.prototype, "mechanism", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], CollectionAttemptDto.prototype, "amount", void 0);
 __decorate([

package/bin/collection/dtos/CollectionIntentSummaryDto.js

@@ -38,12 +38,12 @@ __decorate([
     __metadata("design:type", String)
 ], CollectionIntentSummaryDto.prototype, "chargeId", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], CollectionIntentSummaryDto.prototype, "amount", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], CollectionIntentSummaryDto.prototype, "reserved", void 0);
 __decorate([

package/bin/collection/dtos/CollectionMetricsDto.js

@@ -24,11 +24,11 @@ __decorate([
     __metadata("design:type", Number)
 ], CollectionMetricsDto.prototype, "successRate", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], CollectionMetricsDto.prototype, "amountReserved", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], CollectionMetricsDto.prototype, "amountCollected", void 0);
 __decorate([

package/bin/collection/dtos/CollectionPricingDto.d.ts

@@ -0,0 +1,28 @@
+import { ProductTaxFeeTypeEnum } from '../../productCatalog';
+import { CollectionFeeMode } from '../enums/CollectionFeeMode';
+/**
+ * Tarifa de un cobro, tal como la manda quien lo pide.
+ *
+ * La regla viaja aquí y no sale del catálogo de productos porque quien conoce las condiciones
+ * comerciales de una cartera es el dominio dueño de la deuda, no el procesador: la misma mecánica de
+ * cobro se tarifa distinto según el producto, el tenant o el convenio.
+ *
+ * Viaja la REGLA, no el importe ya calculado. Así la aritmética y el redondeo son los mismos que los
+ * del resto de las transacciones, en vez de que cada dominio reimplemente los suyos y los números
+ * dejen de cuadrar entre sí.
+ */
+export declare class CollectionPricingDto {
+    /**
+     * Fila de `ProductCatalog_GT` con la que se clasifica la transacción resultante — de ahí salen su
+     * tipo y subtipo. La tarifa NO sale de ahí: sale de los campos de abajo.
+     */
+    productCatalogId: string;
+    /** Comisión: porcentaje sobre el monto, o importe fijo, según `feeType`. */
+    fee: number;
+    feeType: ProductTaxFeeTypeEnum;
+    /** Impuesto: porcentaje SOBRE LA COMISIÓN, o importe fijo, según `taxType`. */
+    tax: number;
+    taxType: ProductTaxFeeTypeEnum;
+    /** Quién absorbe la comisión: el cliente por encima de su deuda, o el destino al recibir menos. */
+    feeMode: CollectionFeeMode;
+}

package/bin/collection/dtos/CollectionPricingDto.js

@@ -0,0 +1,55 @@
+"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;
+};
+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.CollectionPricingDto = void 0;
+const class_validator_1 = require("class-validator");
+const productCatalog_1 = require("../../productCatalog");
+const CollectionFeeMode_1 = require("../enums/CollectionFeeMode");
+/**
+ * Tarifa de un cobro, tal como la manda quien lo pide.
+ *
+ * La regla viaja aquí y no sale del catálogo de productos porque quien conoce las condiciones
+ * comerciales de una cartera es el dominio dueño de la deuda, no el procesador: la misma mecánica de
+ * cobro se tarifa distinto según el producto, el tenant o el convenio.
+ *
+ * Viaja la REGLA, no el importe ya calculado. Así la aritmética y el redondeo son los mismos que los
+ * del resto de las transacciones, en vez de que cada dominio reimplemente los suyos y los números
+ * dejen de cuadrar entre sí.
+ */
+class CollectionPricingDto {
+}
+exports.CollectionPricingDto = CollectionPricingDto;
+__decorate([
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], CollectionPricingDto.prototype, "productCatalogId", void 0);
+__decorate([
+    (0, class_validator_1.IsNumber)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], CollectionPricingDto.prototype, "fee", void 0);
+__decorate([
+    (0, class_validator_1.IsEnum)(productCatalog_1.ProductTaxFeeTypeEnum),
+    __metadata("design:type", String)
+], CollectionPricingDto.prototype, "feeType", void 0);
+__decorate([
+    (0, class_validator_1.IsNumber)(),
+    (0, class_validator_1.Min)(0),
+    __metadata("design:type", Number)
+], CollectionPricingDto.prototype, "tax", void 0);
+__decorate([
+    (0, class_validator_1.IsEnum)(productCatalog_1.ProductTaxFeeTypeEnum),
+    __metadata("design:type", String)
+], CollectionPricingDto.prototype, "taxType", void 0);
+__decorate([
+    (0, class_validator_1.IsEnum)(CollectionFeeMode_1.CollectionFeeMode),
+    __metadata("design:type", String)
+], CollectionPricingDto.prototype, "feeMode", void 0);

package/bin/collection/dtos/CollectionProductConfigDto.d.ts

@@ -1,5 +1,14 @@
 import { CollectionSourceDto } from './CollectionSourceDto';
 import { RetryPolicyDto } from './RetryPolicyDto';
+/**
+ * Cómo se cobra un producto: de qué cuentas, en qué orden, y con cuánta insistencia.
+ *
+ * `allowPartial` decide si una fuente puede aportar una parte y el resto se busca en la siguiente, o
+ * si sólo sirve la que cubra el total.
+ *
+ * Versionada: cambiar la cascada de un producto crea una versión nueva en vez de reescribir la
+ * anterior, para que un cobro pueda explicarse con la configuración que regía cuando ocurrió.
+ */
 export declare class CollectionProductConfigDto {
     tenantId: string;
     productId: string;

package/bin/collection/dtos/CollectionProductConfigDto.js

@@ -14,6 +14,15 @@ const class_validator_1 = require("class-validator");
 const class_transformer_1 = require("class-transformer");
 const CollectionSourceDto_1 = require("./CollectionSourceDto");
 const RetryPolicyDto_1 = require("./RetryPolicyDto");
+/**
+ * Cómo se cobra un producto: de qué cuentas, en qué orden, y con cuánta insistencia.
+ *
+ * `allowPartial` decide si una fuente puede aportar una parte y el resto se busca en la siguiente, o
+ * si sólo sirve la que cubra el total.
+ *
+ * Versionada: cambiar la cascada de un producto crea una versión nueva en vez de reescribir la
+ * anterior, para que un cobro pueda explicarse con la configuración que regía cuando ocurrió.
+ */
 class CollectionProductConfigDto {
 }
 exports.CollectionProductConfigDto = CollectionProductConfigDto;

package/bin/collection/dtos/CollectionResultEvent.d.ts

@@ -1,5 +1,8 @@
 import { CollectionResultStatus } from '../enums/CollectionResultStatus';
 import { MechanismType } from '../enums/MechanismType';
+/**
+ * El resultado de un cobro, en la forma en que se anuncia hacia afuera del motor.
+ */
 export declare class CollectionResultEvent {
     attemptId: string;
     intentId: string;

package/bin/collection/dtos/CollectionResultEvent.js

@@ -13,6 +13,9 @@ exports.CollectionResultEvent = void 0;
 const class_validator_1 = require("class-validator");
 const CollectionResultStatus_1 = require("../enums/CollectionResultStatus");
 const MechanismType_1 = require("../enums/MechanismType");
+/**
+ * El resultado de un cobro, en la forma en que se anuncia hacia afuera del motor.
+ */
 class CollectionResultEvent {
 }
 exports.CollectionResultEvent = CollectionResultEvent;
@@ -45,6 +48,6 @@ __decorate([
     __metadata("design:type", String)
 ], CollectionResultEvent.prototype, "mechanism", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], CollectionResultEvent.prototype, "amount", void 0);

package/bin/collection/dtos/CollectionSourceDto.d.ts

@@ -1,5 +1,17 @@
 import { MechanismType } from '../enums/MechanismType';
 import { CurrencyId } from '../../currency/enums/CurrencyId';
+import { CollectionPricingDto } from './CollectionPricingDto';
+/**
+ * Una fuente de la cascada de cobro: de qué cuenta se intenta cobrar, con qué mecanismo y en qué
+ * posición.
+ *
+ * `order` es lo que decide si primero se intenta en pesos o en dólares. El motor las recorre de menor
+ * a mayor y salta las ya intentadas en esa corrida.
+ *
+ * `currency` tiene que corresponder al `mechanism` —el mecanismo fija su moneda al ejecutar— y
+ * `provider` tiene que ser único entre las fuentes de un producto: es la identidad con la que el motor
+ * distingue un intento de otro.
+ */
 export declare class CollectionSourceDto {
     order: number;
     wallet: string;
@@ -7,4 +19,12 @@ export declare class CollectionSourceDto {
     mechanism: MechanismType;
     provider: string;
     fxPolicy?: string;
+    /**
+     * Con qué se tarifa un cobro por esta fuente. Va por fuente y no por producto porque la misma deuda
+     * puede costar distinto según de dónde se cobre: mover dólares no cuesta lo mismo que mover pesos.
+     *
+     * Sin tarifa el cobro se ejecuta igual, pero no deja transacción — sin asiento contable, sin
+     * aparecer en el historial del cliente y sin comisión declarada.
+     */
+    pricing?: CollectionPricingDto;
 }

package/bin/collection/dtos/CollectionSourceDto.js

@@ -11,8 +11,21 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CollectionSourceDto = void 0;
 const class_validator_1 = require("class-validator");
+const class_transformer_1 = require("class-transformer");
 const MechanismType_1 = require("../enums/MechanismType");
 const CurrencyId_1 = require("../../currency/enums/CurrencyId");
+const CollectionPricingDto_1 = require("./CollectionPricingDto");
+/**
+ * Una fuente de la cascada de cobro: de qué cuenta se intenta cobrar, con qué mecanismo y en qué
+ * posición.
+ *
+ * `order` es lo que decide si primero se intenta en pesos o en dólares. El motor las recorre de menor
+ * a mayor y salta las ya intentadas en esa corrida.
+ *
+ * `currency` tiene que corresponder al `mechanism` —el mecanismo fija su moneda al ejecutar— y
+ * `provider` tiene que ser único entre las fuentes de un producto: es la identidad con la que el motor
+ * distingue un intento de otro.
+ */
 class CollectionSourceDto {
 }
 exports.CollectionSourceDto = CollectionSourceDto;
@@ -41,3 +54,9 @@ __decorate([
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
 ], CollectionSourceDto.prototype, "fxPolicy", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.ValidateNested)(),
+    (0, class_transformer_1.Type)(() => CollectionPricingDto_1.CollectionPricingDto),
+    __metadata("design:type", CollectionPricingDto_1.CollectionPricingDto)
+], CollectionSourceDto.prototype, "pricing", void 0);

package/bin/collection/dtos/PendingChargeDto.d.ts

@@ -1,4 +1,14 @@
 import { CurrencyId } from '../../currency/enums/CurrencyId';
+/**
+ * Un cargo vivo, según el dominio que lleva la deuda.
+ *
+ * `amount` es lo que queda por cobrar AHORA, con las reglas del dominio ya aplicadas —mora corrida,
+ * pagos recibidos por otra vía—. El motor no lo recalcula ni lo valida contra nada: cobra lo que aquí
+ * se declare.
+ *
+ * El desglose (capital, interés, impuesto) es opcional y no participa del cobro: viaja para que el
+ * asiento y los reportes puedan reconstruirlo.
+ */
 export declare class PendingChargeDto {
     chargeId: string;
     directoryId: string;

package/bin/collection/dtos/PendingChargeDto.js

@@ -12,6 +12,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.PendingChargeDto = void 0;
 const class_validator_1 = require("class-validator");
 const CurrencyId_1 = require("../../currency/enums/CurrencyId");
+/**
+ * Un cargo vivo, según el dominio que lleva la deuda.
+ *
+ * `amount` es lo que queda por cobrar AHORA, con las reglas del dominio ya aplicadas —mora corrida,
+ * pagos recibidos por otra vía—. El motor no lo recalcula ni lo valida contra nada: cobra lo que aquí
+ * se declare.
+ *
+ * El desglose (capital, interés, impuesto) es opcional y no participa del cobro: viaja para que el
+ * asiento y los reportes puedan reconstruirlo.
+ */
 class PendingChargeDto {
 }
 exports.PendingChargeDto = PendingChargeDto;
@@ -40,7 +50,7 @@ __decorate([
     __metadata("design:type", Number)
 ], PendingChargeDto.prototype, "installmentNumber", void 0);
 __decorate([
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], PendingChargeDto.prototype, "amount", void 0);
 __decorate([
@@ -57,27 +67,27 @@ __decorate([
 ], PendingChargeDto.prototype, "status", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], PendingChargeDto.prototype, "principalAmount", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], PendingChargeDto.prototype, "interestAmount", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], PendingChargeDto.prototype, "taxAmount", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], PendingChargeDto.prototype, "outstandingBalance", void 0);
 __decorate([
     (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsInt)(),
+    (0, class_validator_1.IsNumber)(),
     __metadata("design:type", Number)
 ], PendingChargeDto.prototype, "amountCollected", void 0);
 __decorate([

package/bin/collection/dtos/RetryPolicyDto.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Cada cuánto y hasta cuándo insistir con un cobro que no avanza.
+ *
+ * `backoffSeconds` es la base de una espera que se duplica en cada intento, no un intervalo fijo.
+ * `awaitingWindowDays` acota cuánto tiempo tiene sentido seguir esperando fondos antes de que el cargo
+ * requiera una decisión humana.
+ */
 export declare class RetryPolicyDto {
     maxAttempts: number;
     backoffSeconds: number;

package/bin/collection/dtos/RetryPolicyDto.js

@@ -11,6 +11,13 @@ var __metadata = (this && this.__metadata) || function (k, v) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RetryPolicyDto = void 0;
 const class_validator_1 = require("class-validator");
+/**
+ * Cada cuánto y hasta cuándo insistir con un cobro que no avanza.
+ *
+ * `backoffSeconds` es la base de una espera que se duplica en cada intento, no un intervalo fijo.
+ * `awaitingWindowDays` acota cuánto tiempo tiene sentido seguir esperando fondos antes de que el cargo
+ * requiera una decisión humana.
+ */
 class RetryPolicyDto {
 }
 exports.RetryPolicyDto = RetryPolicyDto;

package/bin/collection/enums/CollectionFeeMode.d.ts

@@ -0,0 +1,6 @@
+export declare enum CollectionFeeMode {
+    /** El cliente paga la deuda MÁS la comisión: se le debita `monto + fee + IVA`. */
+    ON_TOP = "ON_TOP",
+    /** El cliente paga sólo la deuda: se le debita el monto, y la comisión se retiene de lo que se remite. */
+    RETAINED = "RETAINED"
+}

package/bin/collection/enums/CollectionFeeMode.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CollectionFeeMode = void 0;
+var CollectionFeeMode;
+(function (CollectionFeeMode) {
+    /** El cliente paga la deuda MÁS la comisión: se le debita `monto + fee + IVA`. */
+    CollectionFeeMode["ON_TOP"] = "ON_TOP";
+    /** El cliente paga sólo la deuda: se le debita el monto, y la comisión se retiene de lo que se remite. */
+    CollectionFeeMode["RETAINED"] = "RETAINED";
+})(CollectionFeeMode || (exports.CollectionFeeMode = CollectionFeeMode = {}));

package/bin/collection/enums/CollectionResultStatus.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Desenlace de un intento de cobro.
+ *
+ * `NONE` no es un fallo: es que no había con qué cobrar. Un error de sistema —el procesador no
+ * responde, el dominio no contesta— no viaja por aquí, viaja como excepción.
+ */
 export declare enum CollectionResultStatus {
     FULL = "FULL",
     PARTIAL = "PARTIAL",

package/bin/collection/enums/CollectionResultStatus.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CollectionResultStatus = void 0;
+/**
+ * Desenlace de un intento de cobro.
+ *
+ * `NONE` no es un fallo: es que no había con qué cobrar. Un error de sistema —el procesador no
+ * responde, el dominio no contesta— no viaja por aquí, viaja como excepción.
+ */
 var CollectionResultStatus;
 (function (CollectionResultStatus) {
     CollectionResultStatus["FULL"] = "FULL";

package/bin/collection/enums/CollectionState.d.ts

@@ -1,3 +1,10 @@
+/**
+ * En qué punto de su vida está un cobro.
+ *
+ * `COLLECTED` y `CANCELLED` son terminales: no se reintentan ni se revierten. `AWAITING_FUNDS` es el
+ * estado en el que un cobro pasa la mayor parte del tiempo — hay deuda, y falta que el titular tenga
+ * con qué pagarla.
+ */
 export declare enum CollectionState {
     PENDING = "PENDING",
     ATTEMPT = "ATTEMPT",

package/bin/collection/enums/CollectionState.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CollectionState = void 0;
+/**
+ * En qué punto de su vida está un cobro.
+ *
+ * `COLLECTED` y `CANCELLED` son terminales: no se reintentan ni se revierten. `AWAITING_FUNDS` es el
+ * estado en el que un cobro pasa la mayor parte del tiempo — hay deuda, y falta que el titular tenga
+ * con qué pagarla.
+ */
 var CollectionState;
 (function (CollectionState) {
     CollectionState["PENDING"] = "PENDING";

package/bin/collection/enums/MechanismType.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Cómo se mueve el dinero en un cobro. Determina la moneda, la cuenta y si el importe se cobra o sólo
+ * se reserva.
+ *
+ * Los dos `DIRECT` cobran: el dinero sale de la cuenta en el acto. `USD_PREAUTH` sólo congela — el
+ * importe sigue siendo del titular hasta que alguien capture la retención.
+ */
 export declare enum MechanismType {
     USD_PREAUTH = "USD_PREAUTH",
     USD_DIRECT = "USD_DIRECT",

package/bin/collection/enums/MechanismType.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MechanismType = void 0;
+/**
+ * Cómo se mueve el dinero en un cobro. Determina la moneda, la cuenta y si el importe se cobra o sólo
+ * se reserva.
+ *
+ * Los dos `DIRECT` cobran: el dinero sale de la cuenta en el acto. `USD_PREAUTH` sólo congela — el
+ * importe sigue siendo del titular hasta que alguien capture la retención.
+ */
 var MechanismType;
 (function (MechanismType) {
     MechanismType["USD_PREAUTH"] = "USD_PREAUTH";

package/bin/collection/enums/SagaStep.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Paso de la saga de cobro en el que quedó un intent, y desde el que se reanuda.
+ *
+ * El orden es RESOLVE (preguntarle al dominio cuánto se debe) → PICK_SOURCE (elegir de dónde) →
+ * EXECUTE (mover el dinero) → PERSIST (registrarlo) → DISPATCH (avisar al dominio). Un intent
+ * reanudado retoma desde el último paso COMPLETADO, no desde el que falló.
+ */
 export declare enum SagaStep {
     RESOLVE = "RESOLVE",
     PICK_SOURCE = "PICK_SOURCE",

package/bin/collection/enums/SagaStep.js

@@ -1,6 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SagaStep = void 0;
+/**
+ * Paso de la saga de cobro en el que quedó un intent, y desde el que se reanuda.
+ *
+ * El orden es RESOLVE (preguntarle al dominio cuánto se debe) → PICK_SOURCE (elegir de dónde) →
+ * EXECUTE (mover el dinero) → PERSIST (registrarlo) → DISPATCH (avisar al dominio). Un intent
+ * reanudado retoma desde el último paso COMPLETADO, no desde el que falló.
+ */
 var SagaStep;
 (function (SagaStep) {
     SagaStep["RESOLVE"] = "RESOLVE";

package/bin/collection/index.d.ts

@@ -4,6 +4,7 @@ export * from './enums/SagaStep';
 export * from './enums/CollectionResultStatus';
 export * from './enums/DeregisterChargeStatus';
 export * from './enums/RegisterCollectibleStatus';
+export * from './enums/CollectionFeeMode';
 export * from './dtos/PendingChargeDto';
 export * from './dtos/CollectRequest';
 export * from './dtos/CollectResponse';
@@ -18,6 +19,7 @@ export * from './dtos/UpsertProductConfigRequest';
 export * from './dtos/ApplyCollectionResultRequest';
 export * from './dtos/DeregisterChargeResponse';
 export * from './dtos/RegisterCollectibleResponse';
+export * from './dtos/CollectionPricingDto';
 export * from './dtos/ResolvePendingChargesRequest';
 export * from './dtos/MoneyInEvent';
 export * from './dtos/CollectionIntentSummaryDto';

package/bin/collection/index.js

@@ -21,6 +21,7 @@ __exportStar(require("./enums/SagaStep"), exports);
 __exportStar(require("./enums/CollectionResultStatus"), exports);
 __exportStar(require("./enums/DeregisterChargeStatus"), exports);
 __exportStar(require("./enums/RegisterCollectibleStatus"), exports);
+__exportStar(require("./enums/CollectionFeeMode"), exports);
 // DTOs
 __exportStar(require("./dtos/PendingChargeDto"), exports);
 __exportStar(require("./dtos/CollectRequest"), exports);
@@ -36,6 +37,7 @@ __exportStar(require("./dtos/UpsertProductConfigRequest"), exports);
 __exportStar(require("./dtos/ApplyCollectionResultRequest"), exports);
 __exportStar(require("./dtos/DeregisterChargeResponse"), exports);
 __exportStar(require("./dtos/RegisterCollectibleResponse"), exports);
+__exportStar(require("./dtos/CollectionPricingDto"), exports);
 __exportStar(require("./dtos/ResolvePendingChargesRequest"), exports);
 __exportStar(require("./dtos/MoneyInEvent"), exports);
 // DTOs — backoffice de monitoreo

package/package.json

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

package/src/collection/dtos/ApplyCollectionResultRequest.ts

@@ -1,7 +1,15 @@
-import { IsString, IsInt, IsEnum, IsOptional } from 'class-validator';
+import { IsString, IsEnum, IsOptional, IsNumber } from 'class-validator';
 import { CollectionResultStatus } from '../enums/CollectionResultStatus';
 import { MechanismType } from '../enums/MechanismType';
 
+/**
+ * Resultado de un intento de cobro, tal como el motor se lo entrega al dominio dueño de la deuda.
+ *
+ * Se entrega con reintentos hasta que el dominio la acepta respondiendo `true`. Cualquier otra
+ * respuesta se lee como no entregada y el mismo resultado vuelve más tarde, así que aplicarlo tiene
+ * que ser idempotente: el dominio deduplica por `attemptId`, que identifica ESE intento y no el cobro
+ * entero.
+ */
 export class ApplyCollectionResultRequest {
   @IsString() attemptId!: string;      // dedupe idempotente en el dominio
   @IsString() intentId!: string;
@@ -9,8 +17,8 @@ export class ApplyCollectionResultRequest {
   @IsString() domain!: string;
   @IsString() tenantId!: string;
   @IsEnum(CollectionResultStatus) result!: CollectionResultStatus;
-  @IsInt() amountCollected!: number;
-  @IsInt() amountReserved!: number;
+  @IsNumber() amountCollected!: number;
+  @IsNumber() amountReserved!: number;
   @IsEnum(MechanismType) mechanism!: MechanismType;
   @IsOptional() @IsString() holdTxId?: string;
 }

package/src/collection/dtos/AuthorizeCollectionMovementRequest.ts

@@ -1,15 +1,25 @@
-import { IsString, IsInt, IsEnum, IsOptional } from 'class-validator';
+import { IsString, IsEnum, IsOptional, ValidateNested, IsNumber } from 'class-validator';
+import { Type } from 'class-transformer';
 import { MechanismType } from '../enums/MechanismType';
 import { CurrencyId } from '../../currency/enums/CurrencyId';
+import { CollectionPricingDto } from './CollectionPricingDto';
 
 export class AuthorizeCollectionMovementRequest {
   @IsString() executionId!: string;    // idempotencia (@IdempotencyController)
   @IsString() directoryId!: string;
   @IsString() provider!: string;       // lo pone el motor desde la config
   @IsEnum(MechanismType) mechanism!: MechanismType;
-  @IsInt() amount!: number;            // ya convertido por el motor (FX previo)
+  @IsNumber() amount!: number;            // ya convertido por el motor (FX previo)
   @IsEnum(CurrencyId) currencyId!: CurrencyId;
   @IsOptional() @IsString() intentId?: string;
   @IsOptional() @IsString() chargeId?: string;
   @IsOptional() @IsString() holdTxId?: string;
+
+  /**
+   * Tarifa con la que se registra el cobro. Presente, el movimiento deja además una transacción
+   * Fiado: asiento contable, historial visible para el cliente y comisión declarada. Ausente, el
+   * dinero se mueve igual pero sin ese registro — es el comportamiento anterior, y se conserva para
+   * no romper a quien todavía no manda tarifa.
+   */
+  @IsOptional() @ValidateNested() @Type(() => CollectionPricingDto) pricing?: CollectionPricingDto;
 }

package/src/collection/dtos/AuthorizeCollectionMovementResponse.ts

@@ -1,9 +1,15 @@
-import { IsString, IsInt, IsEnum, IsOptional } from 'class-validator';
+import { IsString, IsEnum, IsOptional, IsNumber } from 'class-validator';
 import { CollectionResultStatus } from '../enums/CollectionResultStatus';
 
+/**
+ * Lo que el procesador responde tras ejecutar un movimiento de cobro.
+ *
+ * `amount` es lo reservado o lo cobrado según el mecanismo, y `holdTxId` sólo viene cuando se reservó:
+ * es con lo que después se captura o se libera la retención.
+ */
 export class AuthorizeCollectionMovementResponse {
   @IsEnum(CollectionResultStatus) status!: CollectionResultStatus;
-  @IsInt() amount!: number;            // reservado o cobrado
+  @IsNumber() amount!: number;            // reservado o cobrado
   @IsOptional() @IsString() holdTxId?: string;
   @IsOptional() @IsString() transactionId?: string;
 }

package/src/collection/dtos/CollectRequest.ts

@@ -1,10 +1,19 @@
-import { IsString, IsInt } from 'class-validator';
+import { IsString, IsNumber } from 'class-validator';
 
+/**
+ * Cobro inmediato y síncrono, con el importe ya resuelto por el dominio.
+ *
+ * Es para cuando alguien espera la respuesta —un botón, una liquidación anticipada—. La cobranza
+ * recurrente no va por aquí: para eso está el alta, donde el motor se encarga de perseguir el cargo.
+ *
+ * Idempotente por dominio y cargo: repetirlo sobre un cargo ya cobrado devuelve el resultado anterior
+ * sin volver a mover dinero.
+ */
 export class CollectRequest {
   @IsString() directoryId!: string;
   @IsString() tenantId!: string;
   @IsString() domain!: string;
   @IsString() productId!: string;
   @IsString() chargeId!: string;
-  @IsInt() amount!: number;
+  @IsNumber() amount!: number;
 }

package/src/collection/dtos/CollectResponse.ts

@@ -1,9 +1,18 @@
-import { IsString, IsInt, IsEnum } from 'class-validator';
+import { IsString, IsEnum, IsNumber } from 'class-validator';
 import { CollectionResultStatus } from '../enums/CollectionResultStatus';
 
+/**
+ * Desenlace de un cobro.
+ *
+ * Lo cobrado y lo reservado van separados porque no son lo mismo: lo primero ya salió de la cuenta y
+ * el dominio debe aplicarlo a su cartera; lo segundo sigue siendo del titular, congelado, esperando
+ * que alguien capture la retención.
+ *
+ * `NONE` no es un fallo: el cargo queda vivo esperando fondos, y el motor lo reintenta solo.
+ */
 export class CollectResponse {
   @IsString() intentId!: string;
   @IsEnum(CollectionResultStatus) status!: CollectionResultStatus;
-  @IsInt() amountReserved!: number;
-  @IsInt() amountCollected!: number;
+  @IsNumber() amountReserved!: number;
+  @IsNumber() amountCollected!: number;
 }

package/src/collection/dtos/CollectionAttemptDto.ts

@@ -1,4 +1,4 @@
-import { IsString, IsInt, IsEnum, IsOptional } from 'class-validator';
+import { IsString, IsInt, IsEnum, IsOptional, IsNumber } from 'class-validator';
 import { MechanismType } from '../enums/MechanismType';
 import { CollectionResultStatus } from '../enums/CollectionResultStatus';
 
@@ -8,7 +8,7 @@ export class CollectionAttemptDto {
   @IsString() intentId!: string;
   @IsString() source!: string;
   @IsEnum(MechanismType) mechanism!: MechanismType;
-  @IsInt() amount!: number;
+  @IsNumber() amount!: number;
   @IsOptional() @IsString() holdTxId?: string;
   @IsOptional() @IsEnum(CollectionResultStatus) result?: CollectionResultStatus;
   @IsOptional() @IsString() errorCode?: string;

package/src/collection/dtos/CollectionIntentSummaryDto.ts

@@ -1,4 +1,4 @@
-import { IsString, IsInt, IsBoolean, IsEnum, IsOptional } from 'class-validator';
+import { IsString, IsInt, IsBoolean, IsEnum, IsOptional, IsNumber } from 'class-validator';
 import { CollectionState } from '../enums/CollectionState';
 import { SagaStep } from '../enums/SagaStep';
 
@@ -9,8 +9,8 @@ export class CollectionIntentSummaryDto {
   @IsString() tenantId!: string;
   @IsString() domain!: string;
   @IsString() chargeId!: string;
-  @IsInt() amount!: number;
-  @IsOptional() @IsInt() reserved?: number;
+  @IsNumber() amount!: number;
+  @IsOptional() @IsNumber() reserved?: number;
   @IsEnum(CollectionState) state!: CollectionState;
   @IsEnum(SagaStep) sagaStep!: SagaStep;
   @IsOptional() @IsBoolean() attention?: boolean;

package/src/collection/dtos/CollectionMetricsDto.ts

@@ -4,8 +4,8 @@ import { IsInt, IsNumber, IsObject } from 'class-validator';
 export class CollectionMetricsDto {
   @IsObject() countsByState!: Record<string, number>;
   @IsNumber() successRate!: number;
-  @IsInt() amountReserved!: number;
-  @IsInt() amountCollected!: number;
+  @IsNumber() amountReserved!: number;
+  @IsNumber() amountCollected!: number;
   @IsInt() backlogAwaitingFunds!: number;
   @IsInt() dlqCount!: number;
 }

package/src/collection/dtos/CollectionPricingDto.ts

@@ -0,0 +1,35 @@
+import { IsEnum, IsNumber, IsString, Min } from 'class-validator';
+import { ProductTaxFeeTypeEnum } from '../../productCatalog';
+import { CollectionFeeMode } from '../enums/CollectionFeeMode';
+
+/**
+ * Tarifa de un cobro, tal como la manda quien lo pide.
+ *
+ * La regla viaja aquí y no sale del catálogo de productos porque quien conoce las condiciones
+ * comerciales de una cartera es el dominio dueño de la deuda, no el procesador: la misma mecánica de
+ * cobro se tarifa distinto según el producto, el tenant o el convenio.
+ *
+ * Viaja la REGLA, no el importe ya calculado. Así la aritmética y el redondeo son los mismos que los
+ * del resto de las transacciones, en vez de que cada dominio reimplemente los suyos y los números
+ * dejen de cuadrar entre sí.
+ */
+export class CollectionPricingDto {
+  /**
+   * Fila de `ProductCatalog_GT` con la que se clasifica la transacción resultante — de ahí salen su
+   * tipo y subtipo. La tarifa NO sale de ahí: sale de los campos de abajo.
+   */
+  @IsString() productCatalogId!: string;
+
+  /** Comisión: porcentaje sobre el monto, o importe fijo, según `feeType`. */
+  @IsNumber() @Min(0) fee!: number;
+
+  @IsEnum(ProductTaxFeeTypeEnum) feeType!: ProductTaxFeeTypeEnum;
+
+  /** Impuesto: porcentaje SOBRE LA COMISIÓN, o importe fijo, según `taxType`. */
+  @IsNumber() @Min(0) tax!: number;
+
+  @IsEnum(ProductTaxFeeTypeEnum) taxType!: ProductTaxFeeTypeEnum;
+
+  /** Quién absorbe la comisión: el cliente por encima de su deuda, o el destino al recibir menos. */
+  @IsEnum(CollectionFeeMode) feeMode!: CollectionFeeMode;
+}

package/src/collection/dtos/CollectionProductConfigDto.ts

@@ -3,6 +3,15 @@ import { Type } from 'class-transformer';
 import { CollectionSourceDto } from './CollectionSourceDto';
 import { RetryPolicyDto } from './RetryPolicyDto';
 
+/**
+ * Cómo se cobra un producto: de qué cuentas, en qué orden, y con cuánta insistencia.
+ *
+ * `allowPartial` decide si una fuente puede aportar una parte y el resto se busca en la siguiente, o
+ * si sólo sirve la que cubra el total.
+ *
+ * Versionada: cambiar la cascada de un producto crea una versión nueva en vez de reescribir la
+ * anterior, para que un cobro pueda explicarse con la configuración que regía cuando ocurrió.
+ */
 export class CollectionProductConfigDto {
   @IsString() tenantId!: string;
   @IsString() productId!: string;

package/src/collection/dtos/CollectionResultEvent.ts

@@ -1,7 +1,10 @@
-import { IsString, IsInt, IsEnum } from 'class-validator';
+import { IsString, IsEnum, IsNumber } from 'class-validator';
 import { CollectionResultStatus } from '../enums/CollectionResultStatus';
 import { MechanismType } from '../enums/MechanismType';
 
+/**
+ * El resultado de un cobro, en la forma en que se anuncia hacia afuera del motor.
+ */
 export class CollectionResultEvent {
   @IsString() attemptId!: string;      // dedupe en el consumidor
   @IsString() intentId!: string;
@@ -10,5 +13,5 @@ export class CollectionResultEvent {
   @IsString() chargeId!: string;
   @IsEnum(CollectionResultStatus) status!: CollectionResultStatus;
   @IsEnum(MechanismType) mechanism!: MechanismType;
-  @IsInt() amount!: number;            // reservado o cobrado según mecanismo
+  @IsNumber() amount!: number;            // reservado o cobrado según mecanismo
 }

package/src/collection/dtos/CollectionSourceDto.ts

@@ -1,7 +1,20 @@
-import { IsString, IsInt, IsEnum, IsOptional } from 'class-validator';
+import { IsString, IsInt, IsEnum, IsOptional, ValidateNested } from 'class-validator';
+import { Type } from 'class-transformer';
 import { MechanismType } from '../enums/MechanismType';
 import { CurrencyId } from '../../currency/enums/CurrencyId';
+import { CollectionPricingDto } from './CollectionPricingDto';
 
+/**
+ * Una fuente de la cascada de cobro: de qué cuenta se intenta cobrar, con qué mecanismo y en qué
+ * posición.
+ *
+ * `order` es lo que decide si primero se intenta en pesos o en dólares. El motor las recorre de menor
+ * a mayor y salta las ya intentadas en esa corrida.
+ *
+ * `currency` tiene que corresponder al `mechanism` —el mecanismo fija su moneda al ejecutar— y
+ * `provider` tiene que ser único entre las fuentes de un producto: es la identidad con la que el motor
+ * distingue un intento de otro.
+ */
 export class CollectionSourceDto {
   @IsInt() order!: number;
   @IsString() wallet!: string;
@@ -9,4 +22,13 @@ export class CollectionSourceDto {
   @IsEnum(MechanismType) mechanism!: MechanismType;
   @IsString() provider!: string;
   @IsOptional() @IsString() fxPolicy?: string;
+
+  /**
+   * Con qué se tarifa un cobro por esta fuente. Va por fuente y no por producto porque la misma deuda
+   * puede costar distinto según de dónde se cobre: mover dólares no cuesta lo mismo que mover pesos.
+   *
+   * Sin tarifa el cobro se ejecuta igual, pero no deja transacción — sin asiento contable, sin
+   * aparecer en el historial del cliente y sin comisión declarada.
+   */
+  @IsOptional() @ValidateNested() @Type(() => CollectionPricingDto) pricing?: CollectionPricingDto;
 }

package/src/collection/dtos/PendingChargeDto.ts

@@ -1,6 +1,16 @@
-import { IsString, IsInt, IsOptional, IsEnum, IsObject } from 'class-validator';
+import { IsString, IsInt, IsOptional, IsEnum, IsObject, IsNumber } from 'class-validator';
 import { CurrencyId } from '../../currency/enums/CurrencyId';
 
+/**
+ * Un cargo vivo, según el dominio que lleva la deuda.
+ *
+ * `amount` es lo que queda por cobrar AHORA, con las reglas del dominio ya aplicadas —mora corrida,
+ * pagos recibidos por otra vía—. El motor no lo recalcula ni lo valida contra nada: cobra lo que aquí
+ * se declare.
+ *
+ * El desglose (capital, interés, impuesto) es opcional y no participa del cobro: viaja para que el
+ * asiento y los reportes puedan reconstruirlo.
+ */
 export class PendingChargeDto {
   @IsString() chargeId!: string;          // record_id / INSTALLMENT#n
   @IsString() directoryId!: string;
@@ -8,14 +18,14 @@ export class PendingChargeDto {
   @IsString() domain!: string;            // une-credit | surekeep-retail
   @IsString() parentDebtId!: string;      // credit_id / CREDIT#id
   @IsInt() installmentNumber!: number;    // coupon_number / installment_number
-  @IsInt() amount!: number;               // centavos
+  @IsNumber() amount!: number;               // centavos
   @IsEnum(CurrencyId) currency!: CurrencyId;
   @IsString() dueDate!: string;           // ISO date
   @IsString() status!: string;            // estado del cargo en el dominio (normalizado por el motor)
-  @IsOptional() @IsInt() principalAmount?: number;
-  @IsOptional() @IsInt() interestAmount?: number;
-  @IsOptional() @IsInt() taxAmount?: number;
-  @IsOptional() @IsInt() outstandingBalance?: number;
-  @IsOptional() @IsInt() amountCollected?: number;
+  @IsOptional() @IsNumber() principalAmount?: number;
+  @IsOptional() @IsNumber() interestAmount?: number;
+  @IsOptional() @IsNumber() taxAmount?: number;
+  @IsOptional() @IsNumber() outstandingBalance?: number;
+  @IsOptional() @IsNumber() amountCollected?: number;
   @IsOptional() @IsObject() metadata?: Record<string, unknown>; // por-dominio (fiado_/loanco_interest, imei…)
 }

package/src/collection/dtos/RetryPolicyDto.ts

@@ -1,5 +1,12 @@
 import { IsInt, IsOptional } from 'class-validator';
 
+/**
+ * Cada cuánto y hasta cuándo insistir con un cobro que no avanza.
+ *
+ * `backoffSeconds` es la base de una espera que se duplica en cada intento, no un intervalo fijo.
+ * `awaitingWindowDays` acota cuánto tiempo tiene sentido seguir esperando fondos antes de que el cargo
+ * requiera una decisión humana.
+ */
 export class RetryPolicyDto {
   @IsInt() maxAttempts!: number;
   @IsInt() backoffSeconds!: number;

package/src/collection/enums/CollectionFeeMode.ts

@@ -0,0 +1,6 @@
+export enum CollectionFeeMode {
+  /** El cliente paga la deuda MÁS la comisión: se le debita `monto + fee + IVA`. */
+  ON_TOP = 'ON_TOP',
+  /** El cliente paga sólo la deuda: se le debita el monto, y la comisión se retiene de lo que se remite. */
+  RETAINED = 'RETAINED',
+}

package/src/collection/enums/CollectionResultStatus.ts

@@ -1,3 +1,9 @@
+/**
+ * Desenlace de un intento de cobro.
+ *
+ * `NONE` no es un fallo: es que no había con qué cobrar. Un error de sistema —el procesador no
+ * responde, el dominio no contesta— no viaja por aquí, viaja como excepción.
+ */
 export enum CollectionResultStatus {
   FULL = 'FULL',
   PARTIAL = 'PARTIAL',

package/src/collection/enums/CollectionState.ts

@@ -1,3 +1,10 @@
+/**
+ * En qué punto de su vida está un cobro.
+ *
+ * `COLLECTED` y `CANCELLED` son terminales: no se reintentan ni se revierten. `AWAITING_FUNDS` es el
+ * estado en el que un cobro pasa la mayor parte del tiempo — hay deuda, y falta que el titular tenga
+ * con qué pagarla.
+ */
 export enum CollectionState {
   PENDING = 'PENDING',
   ATTEMPT = 'ATTEMPT',

package/src/collection/enums/MechanismType.ts

@@ -1,3 +1,10 @@
+/**
+ * Cómo se mueve el dinero en un cobro. Determina la moneda, la cuenta y si el importe se cobra o sólo
+ * se reserva.
+ *
+ * Los dos `DIRECT` cobran: el dinero sale de la cuenta en el acto. `USD_PREAUTH` sólo congela — el
+ * importe sigue siendo del titular hasta que alguien capture la retención.
+ */
 export enum MechanismType {
   USD_PREAUTH = 'USD_PREAUTH',
   USD_DIRECT = 'USD_DIRECT',

package/src/collection/enums/SagaStep.ts

@@ -1,3 +1,10 @@
+/**
+ * Paso de la saga de cobro en el que quedó un intent, y desde el que se reanuda.
+ *
+ * El orden es RESOLVE (preguntarle al dominio cuánto se debe) → PICK_SOURCE (elegir de dónde) →
+ * EXECUTE (mover el dinero) → PERSIST (registrarlo) → DISPATCH (avisar al dominio). Un intent
+ * reanudado retoma desde el último paso COMPLETADO, no desde el que falló.
+ */
 export enum SagaStep {
   RESOLVE = 'RESOLVE',
   PICK_SOURCE = 'PICK_SOURCE',

package/src/collection/index.ts

@@ -5,6 +5,7 @@ export * from './enums/SagaStep';
 export * from './enums/CollectionResultStatus';
 export * from './enums/DeregisterChargeStatus';
 export * from './enums/RegisterCollectibleStatus';
+export * from './enums/CollectionFeeMode';
 
 // DTOs
 export * from './dtos/PendingChargeDto';
@@ -21,6 +22,7 @@ export * from './dtos/UpsertProductConfigRequest';
 export * from './dtos/ApplyCollectionResultRequest';
 export * from './dtos/DeregisterChargeResponse';
 export * from './dtos/RegisterCollectibleResponse';
+export * from './dtos/CollectionPricingDto';
 export * from './dtos/ResolvePendingChargesRequest';
 export * from './dtos/MoneyInEvent';