@fiado/type-kit 3.451.0 → 3.453.0

package/_test_/unit/transaction/DisputeRefundEnums.test.ts

@@ -0,0 +1,35 @@
+import 'reflect-metadata';
+import { DisputeRefundType, DisputeRefundStatus } from '../../../src/transaction';
+
+describe('DisputeRefundType', () => {
+  it('expone REFUND, REVERSAL', () => {
+    expect(DisputeRefundType.REFUND).toBe('REFUND');
+    expect(DisputeRefundType.REVERSAL).toBe('REVERSAL');
+  });
+
+  it('no tiene valores de más', () => {
+    expect(Object.values(DisputeRefundType).sort()).toEqual(['REFUND', 'REVERSAL'].sort());
+  });
+});
+
+describe('DisputeRefundStatus', () => {
+  const expected = [
+    'PENDING_AUTHORIZATION',
+    'PENDING_MANUAL_EXECUTION',
+    'EXECUTED',
+    'FAILED',
+    'CANCELLED',
+  ];
+
+  it('expone los 5 estados del ciclo de vida', () => {
+    expect(DisputeRefundStatus.PENDING_AUTHORIZATION).toBe('PENDING_AUTHORIZATION');
+    expect(DisputeRefundStatus.PENDING_MANUAL_EXECUTION).toBe('PENDING_MANUAL_EXECUTION');
+    expect(DisputeRefundStatus.EXECUTED).toBe('EXECUTED');
+    expect(DisputeRefundStatus.FAILED).toBe('FAILED');
+    expect(DisputeRefundStatus.CANCELLED).toBe('CANCELLED');
+  });
+
+  it('no tiene valores de más', () => {
+    expect(Object.values(DisputeRefundStatus).sort()).toEqual(expected.sort());
+  });
+});

package/_test_/unit/transaction/refund-dtos.test.ts

@@ -21,6 +21,8 @@ describe('Refund DTOs', () => {
       refundCase: {
         pathType: RefundPathTypeEnum.DICTAMEN_PROCEDE,
         caseFolio: 'FOLIO-001',
+        folioId: 'e8b34db9-11cc-4d7a-b6c9-7f2a91b8c001',
+        folioEventId: '9a41c3d0-f78b-4d54-9c62-1e8d5f2b7003',
         originalTransactionId: 'TX-123',
         originalAmount: 1000,
         originalChannel: 'SPEI_IN',
@@ -75,4 +77,31 @@ describe('Refund DTOs', () => {
     expect(confirmRequest.speiTrackingKey).toBe('SPE-TRACK-001');
     expect(confirmRequest.executedAt).toBe('2026-09-17T22:00:00Z');
   });
+
+  it('AuthorizeRefundRequest expone folioId y folioEventId como campos requeridos de refundCase', () => {
+    const req: AuthorizeRefundRequest = {
+      idempotencyKey: 'k',
+      directoryId: 'd',
+      peopleId: 'p',
+      productCatalogId: 'MEX_REFUND_PCF',
+      operation: 'ADD',
+      amount: { total: 100, currencyId: 'MXN' },
+      refundChannel: RefundChannelEnum.INTERNAL_PCF,
+      refundCase: {
+        pathType: RefundPathTypeEnum.DICTAMEN_PROCEDE,
+        caseFolio: 'F',
+        folioId: 'uuid-folio',
+        folioEventId: 'uuid-event',
+        originalTransactionId: null,
+        originalAmount: 100,
+        originalChannel: 'PCF_P2P',
+      },
+      approval: { makerUserId: 'm', checkerUserId: null, minuteS3Key: null },
+      reason: 'r',
+      evidence: { dictamenS3Key: null, incidentReportS3Key: null, objectionFormS3Key: null },
+      pldOverrideMinuteS3Key: null,
+    };
+    expect(req.refundCase.folioId).toBe('uuid-folio');
+    expect(req.refundCase.folioEventId).toBe('uuid-event');
+  });
 });

package/bin/transaction/dtos/AuthorizeRefundRequest.d.ts

@@ -19,6 +19,25 @@ export interface AuthorizeRefundRequest {
     refundCase: {
         pathType: RefundPathTypeEnum;
         caseFolio: string;
+        /**
+         * UUID del registro `DisputeOrFraudLog` que originó el reintegro (fuente
+         * autoritativa del folio). El BO lo persiste en el ledger como
+         * `PagoConfiadoTx_GT.disputeOrFraudLogId` para cerrar el vínculo con la
+         * reclamación (antes del rediseño quedaba en "ND").
+         */
+        folioId: string;
+        /**
+         * UUID del evento R27 específico dentro de `DisputeOrFraudLog.statusHistory[]`
+         * que autoriza este reintegro. Preserva el ligado inmutable evento↔movimiento
+         * en `DisputeRefund_GT.folioEventId`: un folio que reingresa (103) tras un
+         * dictamen no procedente y genera un segundo refund puede tener 2 entradas
+         * en `DisputeRefund_GT`, cada una apuntando a su evento R27 propio.
+         *
+         * Lo obtiene el Dashboard del response de `disputes-business` al firmar el
+         * dictamen (`lastEvent.eventId`). Es inmutable — no se recalcula ni se
+         * reasigna una vez enviado.
+         */
+        folioEventId: string;
         originalTransactionId: string | null;
         originalAmount: number;
         /**

package/bin/transaction/dtos/DisputeRefundRecord.d.ts

@@ -0,0 +1,68 @@
+import { RefundChannelEnum } from '../enums/RefundChannelEnum';
+import { DisputeRefundType } from '../enums/DisputeRefundType';
+import { DisputeRefundStatus } from '../enums/DisputeRefundStatus';
+/**
+ * Registro canónico de un movimiento de dinero (REFUND o REVERSAL) ligado a
+ * un folio R27 de reclamación. Es el shape 1:1 de una fila de la tabla DDB
+ * `DisputeRefund_GT`.
+ *
+ * Modelo:
+ *   - Un folio R27 puede tener 0, 1 o 2 filas en DisputeRefund_GT.
+ *   - 1 fila `type=REFUND` cuando el reintegro se ejecutó.
+ *   - 2 filas (REFUND + REVERSAL) cuando el reintegro fue revertido por
+ *     dictamen tardío que confirmó 2FA original (Circular 12/2018
+ *     Disposición 35.a Banxico).
+ *   - `folioEventId` apunta al evento R27 específico (no solo al folio)
+ *     para preservar el ligado inmutable cuando un folio reingresa (103)
+ *     tras un dictamen no procedente.
+ *   - `relatedRefundId` solo aplica cuando `type=REVERSAL` — apunta al `id`
+ *     del REFUND que se está revirtiendo.
+ *   - `txId` es `null` durante `PENDING_AUTHORIZATION`; se popula al crear
+ *     la tx en el ledger (`PagoConfiadoTx_GT`).
+ */
+export interface DisputeRefundRecord {
+    id: string;
+    folioId: string;
+    folioEventId: string;
+    type: DisputeRefundType;
+    channel: RefundChannelEnum;
+    status: DisputeRefundStatus;
+    relatedRefundId: string | null;
+    txId: string | null;
+    amount: number;
+    currencyId: 'MXN';
+    caseFolio: string;
+    targetDirectoryId: string;
+    manualExecution: DisputeRefundManualExecution | null;
+    approval: DisputeRefundApproval;
+    reason: string | null;
+    createdAt: number;
+    updatedAt: number;
+    failureReason: string | null;
+}
+/**
+ * Metadatos específicos del canal SPEI_OUT_MANUAL. `null` cuando el canal es
+ * INTERNAL_PCF (transferencia intra-wallet sin salida SPEI).
+ */
+export interface DisputeRefundManualExecution {
+    targetClabe: string | null;
+    targetBankId: string | null;
+    targetName: string | null;
+    instructionS3Key: string | null;
+    confirmedTrackingKey: string | null;
+    confirmedAt: number | null;
+    confirmedByUserId: string | null;
+}
+/**
+ * Cadena de aprobación heredada de Política SP1 §10:
+ *   L1 ($5,000 MXN) → requiere checker.
+ *   L2 ($50,000 MXN) → requiere checker + minuta firmada.
+ * `pldOverrideMinuteS3Key` cubre el caso en que el titular está en lista
+ * negra PLD y el reintegro procede solo con acta de comité.
+ */
+export interface DisputeRefundApproval {
+    makerUserId: string;
+    checkerUserId: string | null;
+    minuteS3Key: string | null;
+    pldOverrideMinuteS3Key: string | null;
+}

package/bin/transaction/dtos/DisputeRefundRecord.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/transaction/enums/DisputeRefundStatus.d.ts

@@ -0,0 +1,7 @@
+export declare enum DisputeRefundStatus {
+    PENDING_AUTHORIZATION = "PENDING_AUTHORIZATION",
+    PENDING_MANUAL_EXECUTION = "PENDING_MANUAL_EXECUTION",
+    EXECUTED = "EXECUTED",
+    FAILED = "FAILED",
+    CANCELLED = "CANCELLED"
+}

package/bin/transaction/enums/DisputeRefundStatus.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisputeRefundStatus = void 0;
+var DisputeRefundStatus;
+(function (DisputeRefundStatus) {
+    DisputeRefundStatus["PENDING_AUTHORIZATION"] = "PENDING_AUTHORIZATION";
+    DisputeRefundStatus["PENDING_MANUAL_EXECUTION"] = "PENDING_MANUAL_EXECUTION";
+    DisputeRefundStatus["EXECUTED"] = "EXECUTED";
+    DisputeRefundStatus["FAILED"] = "FAILED";
+    DisputeRefundStatus["CANCELLED"] = "CANCELLED";
+})(DisputeRefundStatus || (exports.DisputeRefundStatus = DisputeRefundStatus = {}));

package/bin/transaction/enums/DisputeRefundType.d.ts

@@ -0,0 +1,4 @@
+export declare enum DisputeRefundType {
+    REFUND = "REFUND",
+    REVERSAL = "REVERSAL"
+}

package/bin/transaction/enums/DisputeRefundType.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DisputeRefundType = void 0;
+var DisputeRefundType;
+(function (DisputeRefundType) {
+    DisputeRefundType["REFUND"] = "REFUND";
+    DisputeRefundType["REVERSAL"] = "REVERSAL";
+})(DisputeRefundType || (exports.DisputeRefundType = DisputeRefundType = {}));

package/bin/transaction/enums/RefundManualExecutionStatus.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @deprecated Use `DisputeRefundStatus` en su lugar. Este enum tiene scope
+ * estrecho (solo canal SPEI_OUT_MANUAL, sin estados de autorización previa,
+ * sin failure state) y se retira junto con la tabla `RefundManualExecution_GT`
+ * en el cleanup que sigue a la migración de código a `DisputeRefund_GT`.
+ */
 export declare enum RefundManualExecutionStatus {
     PENDING_MANUAL_EXECUTION = "PENDING_MANUAL_EXECUTION",
     EXECUTED = "EXECUTED",

package/bin/transaction/enums/RefundManualExecutionStatus.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RefundManualExecutionStatus = void 0;
+/**
+ * @deprecated Use `DisputeRefundStatus` en su lugar. Este enum tiene scope
+ * estrecho (solo canal SPEI_OUT_MANUAL, sin estados de autorización previa,
+ * sin failure state) y se retira junto con la tabla `RefundManualExecution_GT`
+ * en el cleanup que sigue a la migración de código a `DisputeRefund_GT`.
+ */
 var RefundManualExecutionStatus;
 (function (RefundManualExecutionStatus) {
     RefundManualExecutionStatus["PENDING_MANUAL_EXECUTION"] = "PENDING_MANUAL_EXECUTION";

package/bin/transaction/index.d.ts

@@ -17,6 +17,7 @@ export * from './dtos/ActivityProblemGetResponse';
 export * from './dtos/AuthorizeRefundRequest';
 export * from './dtos/ReverseRefundRequest';
 export * from './dtos/ConfirmManualExecutionRequest';
+export * from './dtos/DisputeRefundRecord';
 export * from './dtos/internal/BaseProviderTransaction';
 export * from './dtos/internal/BaseProviderTransactionQueryParams';
 export * from './dtos/internal/CentralPaymentsQueryParams';
@@ -39,3 +40,5 @@ export * from './enums/ActivityProblemStatusEnum';
 export * from './enums/RefundChannelEnum';
 export * from './enums/RefundPathTypeEnum';
 export * from './enums/RefundManualExecutionStatus';
+export * from './enums/DisputeRefundType';
+export * from './enums/DisputeRefundStatus';

package/bin/transaction/index.js

@@ -34,6 +34,7 @@ __exportStar(require("./dtos/ActivityProblemGetResponse"), exports);
 __exportStar(require("./dtos/AuthorizeRefundRequest"), exports);
 __exportStar(require("./dtos/ReverseRefundRequest"), exports);
 __exportStar(require("./dtos/ConfirmManualExecutionRequest"), exports);
+__exportStar(require("./dtos/DisputeRefundRecord"), exports);
 __exportStar(require("./dtos/internal/BaseProviderTransaction"), exports);
 __exportStar(require("./dtos/internal/BaseProviderTransactionQueryParams"), exports);
 __exportStar(require("./dtos/internal/CentralPaymentsQueryParams"), exports);
@@ -57,3 +58,5 @@ __exportStar(require("./enums/ActivityProblemStatusEnum"), exports);
 __exportStar(require("./enums/RefundChannelEnum"), exports);
 __exportStar(require("./enums/RefundPathTypeEnum"), exports);
 __exportStar(require("./enums/RefundManualExecutionStatus"), exports);
+__exportStar(require("./enums/DisputeRefundType"), exports);
+__exportStar(require("./enums/DisputeRefundStatus"), exports);

package/package.json

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

package/src/transaction/dtos/AuthorizeRefundRequest.ts

@@ -17,6 +17,25 @@ export interface AuthorizeRefundRequest {
     refundCase: {
         pathType: RefundPathTypeEnum;
         caseFolio: string;
+        /**
+         * UUID del registro `DisputeOrFraudLog` que originó el reintegro (fuente
+         * autoritativa del folio). El BO lo persiste en el ledger como
+         * `PagoConfiadoTx_GT.disputeOrFraudLogId` para cerrar el vínculo con la
+         * reclamación (antes del rediseño quedaba en "ND").
+         */
+        folioId: string;
+        /**
+         * UUID del evento R27 específico dentro de `DisputeOrFraudLog.statusHistory[]`
+         * que autoriza este reintegro. Preserva el ligado inmutable evento↔movimiento
+         * en `DisputeRefund_GT.folioEventId`: un folio que reingresa (103) tras un
+         * dictamen no procedente y genera un segundo refund puede tener 2 entradas
+         * en `DisputeRefund_GT`, cada una apuntando a su evento R27 propio.
+         *
+         * Lo obtiene el Dashboard del response de `disputes-business` al firmar el
+         * dictamen (`lastEvent.eventId`). Es inmutable — no se recalcula ni se
+         * reasigna una vez enviado.
+         */
+        folioEventId: string;
         originalTransactionId: string | null;
         originalAmount: number;
         /**

package/src/transaction/dtos/DisputeRefundRecord.ts

@@ -0,0 +1,71 @@
+import { RefundChannelEnum } from '../enums/RefundChannelEnum';
+import { DisputeRefundType } from '../enums/DisputeRefundType';
+import { DisputeRefundStatus } from '../enums/DisputeRefundStatus';
+
+/**
+ * Registro canónico de un movimiento de dinero (REFUND o REVERSAL) ligado a
+ * un folio R27 de reclamación. Es el shape 1:1 de una fila de la tabla DDB
+ * `DisputeRefund_GT`.
+ *
+ * Modelo:
+ *   - Un folio R27 puede tener 0, 1 o 2 filas en DisputeRefund_GT.
+ *   - 1 fila `type=REFUND` cuando el reintegro se ejecutó.
+ *   - 2 filas (REFUND + REVERSAL) cuando el reintegro fue revertido por
+ *     dictamen tardío que confirmó 2FA original (Circular 12/2018
+ *     Disposición 35.a Banxico).
+ *   - `folioEventId` apunta al evento R27 específico (no solo al folio)
+ *     para preservar el ligado inmutable cuando un folio reingresa (103)
+ *     tras un dictamen no procedente.
+ *   - `relatedRefundId` solo aplica cuando `type=REVERSAL` — apunta al `id`
+ *     del REFUND que se está revirtiendo.
+ *   - `txId` es `null` durante `PENDING_AUTHORIZATION`; se popula al crear
+ *     la tx en el ledger (`PagoConfiadoTx_GT`).
+ */
+export interface DisputeRefundRecord {
+    id: string;
+    folioId: string;
+    folioEventId: string;
+    type: DisputeRefundType;
+    channel: RefundChannelEnum;
+    status: DisputeRefundStatus;
+    relatedRefundId: string | null;
+    txId: string | null;
+    amount: number;
+    currencyId: 'MXN';
+    caseFolio: string;
+    targetDirectoryId: string;
+    manualExecution: DisputeRefundManualExecution | null;
+    approval: DisputeRefundApproval;
+    reason: string | null;
+    createdAt: number;
+    updatedAt: number;
+    failureReason: string | null;
+}
+
+/**
+ * Metadatos específicos del canal SPEI_OUT_MANUAL. `null` cuando el canal es
+ * INTERNAL_PCF (transferencia intra-wallet sin salida SPEI).
+ */
+export interface DisputeRefundManualExecution {
+    targetClabe: string | null;
+    targetBankId: string | null;
+    targetName: string | null;
+    instructionS3Key: string | null;
+    confirmedTrackingKey: string | null;
+    confirmedAt: number | null;
+    confirmedByUserId: string | null;
+}
+
+/**
+ * Cadena de aprobación heredada de Política SP1 §10:
+ *   L1 ($5,000 MXN) → requiere checker.
+ *   L2 ($50,000 MXN) → requiere checker + minuta firmada.
+ * `pldOverrideMinuteS3Key` cubre el caso en que el titular está en lista
+ * negra PLD y el reintegro procede solo con acta de comité.
+ */
+export interface DisputeRefundApproval {
+    makerUserId: string;
+    checkerUserId: string | null;
+    minuteS3Key: string | null;
+    pldOverrideMinuteS3Key: string | null;
+}

package/src/transaction/enums/DisputeRefundStatus.ts

@@ -0,0 +1,7 @@
+export enum DisputeRefundStatus {
+    PENDING_AUTHORIZATION = "PENDING_AUTHORIZATION",
+    PENDING_MANUAL_EXECUTION = "PENDING_MANUAL_EXECUTION",
+    EXECUTED = "EXECUTED",
+    FAILED = "FAILED",
+    CANCELLED = "CANCELLED",
+}

package/src/transaction/enums/DisputeRefundType.ts

@@ -0,0 +1,4 @@
+export enum DisputeRefundType {
+    REFUND = "REFUND",
+    REVERSAL = "REVERSAL",
+}

package/src/transaction/enums/RefundManualExecutionStatus.ts

@@ -1,3 +1,9 @@
+/**
+ * @deprecated Use `DisputeRefundStatus` en su lugar. Este enum tiene scope
+ * estrecho (solo canal SPEI_OUT_MANUAL, sin estados de autorización previa,
+ * sin failure state) y se retira junto con la tabla `RefundManualExecution_GT`
+ * en el cleanup que sigue a la migración de código a `DisputeRefund_GT`.
+ */
 export enum RefundManualExecutionStatus {
     PENDING_MANUAL_EXECUTION = "PENDING_MANUAL_EXECUTION",
     EXECUTED = "EXECUTED",

package/src/transaction/index.ts

@@ -18,6 +18,7 @@ export * from './dtos/ActivityProblemGetResponse';
 export * from './dtos/AuthorizeRefundRequest';
 export * from './dtos/ReverseRefundRequest';
 export * from './dtos/ConfirmManualExecutionRequest';
+export * from './dtos/DisputeRefundRecord';
 
 export * from './dtos/internal/BaseProviderTransaction';
 export * from './dtos/internal/BaseProviderTransactionQueryParams';
@@ -44,3 +45,5 @@ export * from './enums/ActivityProblemStatusEnum';
 export * from './enums/RefundChannelEnum';
 export * from './enums/RefundPathTypeEnum';
 export * from './enums/RefundManualExecutionStatus';
+export * from './enums/DisputeRefundType';
+export * from './enums/DisputeRefundStatus';