@fiado/type-kit 3.451.0 → 3.452.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/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.452.0",
   "description": "",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",

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';