@fiado/type-kit 3.163.0 → 3.164.0

package/_test_/unit/remittance/resolveExceptionCode.test.ts

@@ -0,0 +1,37 @@
+import { RemittanceExceptionCode } from "../../../src/remittance/enums/RemittanceExceptionCode";
+import {
+    REMITTANCE_EXCEPTION_CATALOG,
+    resolveExceptionCode,
+} from "../../../src/remittance/dtos/RemittanceExceptionCatalog";
+
+describe("resolveExceptionCode", () => {
+    it("HOLD con sub-status de timeout → HOLD_PROVIDER_TIMEOUT", () => {
+        expect(resolveExceptionCode("HOLD", "SENDMONEY_TIMEOUT")).toBe(RemittanceExceptionCode.HOLD_PROVIDER_TIMEOUT);
+    });
+    it("HOLD sin sub-status → HOLD_GENERIC", () => {
+        expect(resolveExceptionCode("HOLD")).toBe(RemittanceExceptionCode.HOLD_GENERIC);
+    });
+    it("CANCELLATION con cancelReason USER_REQUESTED → CANCEL_USER_REQUESTED", () => {
+        expect(resolveExceptionCode("CANCELLATION_IN_PROGRESS", undefined, "USER_REQUESTED")).toBe(RemittanceExceptionCode.CANCEL_USER_REQUESTED);
+    });
+    it("IN_PROCESS → INPROCESS_STALE_24H", () => {
+        expect(resolveExceptionCode("IN_PROCESS")).toBe(RemittanceExceptionCode.INPROCESS_STALE_24H);
+    });
+    it("HOLD con sub-status desconocido → HOLD_GENERIC (no UNKNOWN)", () => {
+        const code = resolveExceptionCode("HOLD", "ZZZ_NUEVO_CODIGO_UNIR");
+        expect(code).toBe(RemittanceExceptionCode.HOLD_GENERIC);
+        expect(REMITTANCE_EXCEPTION_CATALOG[code]).toBeDefined();
+    });
+    it("status totalmente inesperado → UNKNOWN con catálogo definido", () => {
+        const code = resolveExceptionCode("PLASMA");
+        expect(code).toBe(RemittanceExceptionCode.UNKNOWN);
+        expect(REMITTANCE_EXCEPTION_CATALOG[code].motivo.length).toBeGreaterThan(0);
+    });
+    it("todo our-code tiene entrada de catálogo (motivo+acción no vacíos)", () => {
+        for (const code of Object.values(RemittanceExceptionCode)) {
+            const entry = REMITTANCE_EXCEPTION_CATALOG[code];
+            expect(entry?.motivo?.length ?? 0).toBeGreaterThan(0);
+            expect(entry?.accionSugerida?.length ?? 0).toBeGreaterThan(0);
+        }
+    });
+});

package/bin/cognitoBackofficeConnector/dtos/MfaPoolConfig.d.ts

@@ -0,0 +1,7 @@
+declare const ALLOWED_MFA_TYPES: readonly ["SOFTWARE_TOKEN_MFA"];
+export type AllowedMfaType = (typeof ALLOWED_MFA_TYPES)[number];
+export declare class MfaPoolConfig {
+    requireMfa: boolean;
+    mfaTypes: AllowedMfaType[];
+}
+export {};

package/bin/cognitoBackofficeConnector/dtos/MfaPoolConfig.js

@@ -0,0 +1,36 @@
+"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.MfaPoolConfig = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const MfaTypesRequiresOne_1 = require("../validators/MfaTypesRequiresOne");
+// EMAIL_OTP removido (3.41.0): el cognito-backoffice-connector no provisiona
+// EmailMfaConfiguration a nivel pool (requiere infra SES que no está montada
+// y la integración con messages-lambda aún no tiene diseño). Ver TD-020 +
+// DEC-001 en cognito-backoffice-connector/docs/. Si se reintroduce, agregar
+// 'EMAIL_OTP' a este array.
+const ALLOWED_MFA_TYPES = ['SOFTWARE_TOKEN_MFA'];
+class MfaPoolConfig {
+}
+exports.MfaPoolConfig = MfaPoolConfig;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], MfaPoolConfig.prototype, "requireMfa", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsArray)(),
+    (0, class_validator_1.IsIn)(ALLOWED_MFA_TYPES, { each: true }),
+    (0, class_validator_1.Validate)(MfaTypesRequiresOne_1.MfaTypesRequiresOne),
+    __metadata("design:type", Array)
+], MfaPoolConfig.prototype, "mfaTypes", void 0);

package/bin/cognitoBackofficeConnector/dtos/PoolConfigResponse.d.ts

@@ -0,0 +1,20 @@
+import { PoolKind } from '../../rbac/enums/PoolKind';
+/**
+ * Shape del `PoolConfigRow` expuesto al caller (BFF M18 / otros lambdas Fiado).
+ * Refleja la configuración de un Cognito User Pool registrado en la tabla
+ * `PoolConfigs_GT` del lambda `cognito-backoffice-connector`.
+ */
+export declare class PoolConfigResponse {
+    userPoolId: string;
+    userPoolArn: string;
+    region: string;
+    poolKind: PoolKind;
+    displayName: string;
+    appClients: Record<string, {
+        clientId: string;
+        clientName: string;
+    }>;
+    status: 'active' | 'deprecated';
+    createdAt: number;
+    updatedAt: number;
+}

package/bin/cognitoBackofficeConnector/dtos/PoolConfigResponse.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolConfigResponse = void 0;
+/**
+ * Shape del `PoolConfigRow` expuesto al caller (BFF M18 / otros lambdas Fiado).
+ * Refleja la configuración de un Cognito User Pool registrado en la tabla
+ * `PoolConfigs_GT` del lambda `cognito-backoffice-connector`.
+ */
+class PoolConfigResponse {
+}
+exports.PoolConfigResponse = PoolConfigResponse;

package/bin/cognitoBackofficeConnector/dtos/PoolsListResponse.d.ts

@@ -0,0 +1,4 @@
+import { PoolConfigResponse } from './PoolConfigResponse';
+export declare class PoolsListResponse {
+    pools: PoolConfigResponse[];
+}

package/bin/cognitoBackofficeConnector/dtos/PoolsListResponse.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolsListResponse = void 0;
+class PoolsListResponse {
+}
+exports.PoolsListResponse = PoolsListResponse;

package/bin/cognitoBackofficeConnector/validators/MfaTypesRequiresOne.d.ts

@@ -0,0 +1,17 @@
+import { ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+/**
+ * Cross-field validator: si `requireMfa: true`, entonces `mfaTypes` debe tener
+ * al menos 1 elemento. Si `requireMfa: false`, `mfaTypes` puede ser vacío.
+ *
+ * Razón: cuando el pool nace con MFA habilitado, el connector llama
+ * `SetUserPoolMfaConfigCommand` con la lista de tipos del DTO. Si el array
+ * llega vacío con `requireMfa: true`, el SDK rechaza con InvalidParameterException
+ * y el pool queda en estado inconsistente (MfaConfiguration:'ON' sin tipos).
+ * Mejor rechazar en validación del DTO antes de tocar AWS.
+ *
+ * Ver pivote v1.4.1 TD-017 cerrado + spec doc §1 R3.
+ */
+export declare class MfaTypesRequiresOne implements ValidatorConstraintInterface {
+    validate(mfaTypes: unknown, args: ValidationArguments): boolean;
+    defaultMessage(): string;
+}

package/bin/cognitoBackofficeConnector/validators/MfaTypesRequiresOne.js

@@ -0,0 +1,39 @@
+"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.MfaTypesRequiresOne = void 0;
+const class_validator_1 = require("class-validator");
+/**
+ * Cross-field validator: si `requireMfa: true`, entonces `mfaTypes` debe tener
+ * al menos 1 elemento. Si `requireMfa: false`, `mfaTypes` puede ser vacío.
+ *
+ * Razón: cuando el pool nace con MFA habilitado, el connector llama
+ * `SetUserPoolMfaConfigCommand` con la lista de tipos del DTO. Si el array
+ * llega vacío con `requireMfa: true`, el SDK rechaza con InvalidParameterException
+ * y el pool queda en estado inconsistente (MfaConfiguration:'ON' sin tipos).
+ * Mejor rechazar en validación del DTO antes de tocar AWS.
+ *
+ * Ver pivote v1.4.1 TD-017 cerrado + spec doc §1 R3.
+ */
+let MfaTypesRequiresOne = class MfaTypesRequiresOne {
+    validate(mfaTypes, args) {
+        const obj = args.object;
+        if (obj.requireMfa === true) {
+            return Array.isArray(mfaTypes) && mfaTypes.length >= 1;
+        }
+        // requireMfa: false → cualquier mfaTypes pasa.
+        return true;
+    }
+    defaultMessage() {
+        return 'mfaTypes requiere al menos un tipo cuando requireMfa=true';
+    }
+};
+exports.MfaTypesRequiresOne = MfaTypesRequiresOne;
+exports.MfaTypesRequiresOne = MfaTypesRequiresOne = __decorate([
+    (0, class_validator_1.ValidatorConstraint)({ name: 'MfaTypesRequiresOneWhenMfaRequired', async: false })
+], MfaTypesRequiresOne);

package/bin/places/dtos/CashInFeeDto.d.ts

@@ -0,0 +1,17 @@
+import { CurrencyId } from '../../currency/enums/CurrencyId';
+/**
+ * Comisión que cobra un punto de cash-in (lo que el lambda MUESTRA, no cobra).
+ * - GreenDot (US): representativo por cadena → `fixed` + `cap` (cada tienda cobra hasta el tope).
+ * - Passport (MX): por red → `fixed` + `percentage`.
+ * Response DTO — sin decoradores de validación.
+ */
+export declare class CashInFeeDto {
+    /** Comisión fija, en la moneda del país. */
+    fixed?: number;
+    /** Porcentaje del monto depositado (0–100). */
+    percentage?: number;
+    /** Tope máximo de comisión (GreenDot: el asociado cobra hasta este cap). */
+    cap?: number;
+    /** Moneda del fee: USD (GreenDot) | MXN (Passport). */
+    currency: CurrencyId;
+}

package/bin/places/dtos/CashInFeeDto.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CashInFeeDto = void 0;
+/**
+ * Comisión que cobra un punto de cash-in (lo que el lambda MUESTRA, no cobra).
+ * - GreenDot (US): representativo por cadena → `fixed` + `cap` (cada tienda cobra hasta el tope).
+ * - Passport (MX): por red → `fixed` + `percentage`.
+ * Response DTO — sin decoradores de validación.
+ */
+class CashInFeeDto {
+}
+exports.CashInFeeDto = CashInFeeDto;

package/bin/rbac/enums/PoolKind.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tipo de User Pool de Cognito desde la perspectiva del modelo RBAC Fiado.
+ *
+ * Origen: spec del proyecto `cognito-backoffice-connector` (Fase 0, componente 01
+ * documento `docs/superpowers/specs/2026-05-26-cognito-connector-decisiones-pendientes-design.md`).
+ *
+ * Decisión (TD-003): el proyecto converge en estos 2 valores. El documento componente 03
+ * lista 3 valores (incluyendo una variante adicional) pero queda como outlier — la
+ * decisión vigente en los 6 docs restantes y en el plan de implementación es 2 valores:
+ *  - BACKOFFICE_PLATFORM — pool del backoffice de plataforma (cross-tenant)
+ *  - BACKOFFICE_TENANT — pool por tenant (multi-tenant isolation)
+ */
+export declare enum PoolKind {
+    BACKOFFICE_PLATFORM = "BACKOFFICE_PLATFORM",
+    BACKOFFICE_TENANT = "BACKOFFICE_TENANT"
+}

package/bin/rbac/enums/PoolKind.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PoolKind = void 0;
+/**
+ * Tipo de User Pool de Cognito desde la perspectiva del modelo RBAC Fiado.
+ *
+ * Origen: spec del proyecto `cognito-backoffice-connector` (Fase 0, componente 01
+ * documento `docs/superpowers/specs/2026-05-26-cognito-connector-decisiones-pendientes-design.md`).
+ *
+ * Decisión (TD-003): el proyecto converge en estos 2 valores. El documento componente 03
+ * lista 3 valores (incluyendo una variante adicional) pero queda como outlier — la
+ * decisión vigente en los 6 docs restantes y en el plan de implementación es 2 valores:
+ *  - BACKOFFICE_PLATFORM — pool del backoffice de plataforma (cross-tenant)
+ *  - BACKOFFICE_TENANT — pool por tenant (multi-tenant isolation)
+ */
+var PoolKind;
+(function (PoolKind) {
+    PoolKind["BACKOFFICE_PLATFORM"] = "BACKOFFICE_PLATFORM";
+    PoolKind["BACKOFFICE_TENANT"] = "BACKOFFICE_TENANT";
+})(PoolKind || (exports.PoolKind = PoolKind = {}));

package/bin/rbac/index.d.ts

@@ -0,0 +1 @@
+export * from './enums/PoolKind';

package/bin/rbac/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./enums/PoolKind"), exports);

package/bin/remittance/dtos/RemittanceExceptionCatalog.d.ts

@@ -0,0 +1,13 @@
+import { RemittanceExceptionCode } from "../enums/RemittanceExceptionCode";
+export interface ExceptionCatalogEntry {
+    motivo: string;
+    accionSugerida: string;
+}
+/** our-code → texto ya traducido (español). El front lo muestra tal cual. */
+export declare const REMITTANCE_EXCEPTION_CATALOG: Record<RemittanceExceptionCode, ExceptionCatalogEntry>;
+/**
+ * Resuelve el our-code a partir del status + los códigos crudos de UNIR.
+ * Fallback por bucket (HOLD_GENERIC / CANCEL_GENERIC / INPROCESS_STALE_24H) y
+ * UNKNOWN para status inesperados. Nunca lanza.
+ */
+export declare function resolveExceptionCode(status: string, unirSubStatus?: string | null, cancelReason?: string | null): RemittanceExceptionCode;

package/bin/remittance/dtos/RemittanceExceptionCatalog.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REMITTANCE_EXCEPTION_CATALOG = void 0;
+exports.resolveExceptionCode = resolveExceptionCode;
+const RemittanceExceptionCode_1 = require("../enums/RemittanceExceptionCode");
+/** our-code → texto ya traducido (español). El front lo muestra tal cual. */
+exports.REMITTANCE_EXCEPTION_CATALOG = {
+    [RemittanceExceptionCode_1.RemittanceExceptionCode.HOLD_DISPERSAL_UNCONFIRMED]: {
+        motivo: "El proveedor no ha confirmado la dispersión de fondos.",
+        accionSugerida: "Investigar el estado de la dispersión. Si supera 48h en HOLD, escalar a soporte del proveedor.",
+    },
+    [RemittanceExceptionCode_1.RemittanceExceptionCode.HOLD_PROVIDER_TIMEOUT]: {
+        motivo: "Tiempo de espera agotado con el proveedor · sin confirmar dispersión.",
+        accionSugerida: "Investigar el estado de la transacción. Si supera 48h en HOLD, escalar a soporte del proveedor.",
+    },
+    [RemittanceExceptionCode_1.RemittanceExceptionCode.HOLD_COMPLIANCE_REVIEW]: {
+        motivo: "El proveedor puso la transacción en revisión de cumplimiento.",
+        accionSugerida: "Monitorear. Si el proveedor no libera en 72h, escalar a soporte.",
+    },
+    [RemittanceExceptionCode_1.RemittanceExceptionCode.HOLD_GENERIC]: {
+        motivo: "El proveedor marcó la transacción con un problema.",
+        accionSugerida: "Investigar el estado de la transacción. Si supera 48h en HOLD, escalar a soporte del proveedor.",
+    },
+    [RemittanceExceptionCode_1.RemittanceExceptionCode.CANCEL_USER_REQUESTED]: {
+        motivo: "El cliente canceló la transacción. Esperando que el proveedor confirme la devolución de fondos.",
+        accionSugerida: "Monitorear. La devolución al monedero se dispara automáticamente al confirmar el proveedor. Si supera 72h, escalar a tesorería.",
+    },
+    [RemittanceExceptionCode_1.RemittanceExceptionCode.CANCEL_PROVIDER_INITIATED]: {
+        motivo: "El proveedor inició la cancelación de la transacción.",
+        accionSugerida: "Monitorear la confirmación de devolución. Si supera 72h, escalar a tesorería.",
+    },
+    [RemittanceExceptionCode_1.RemittanceExceptionCode.CANCEL_GENERIC]: {
+        motivo: "Cancelación en proceso. Esperando confirmación del proveedor.",
+        accionSugerida: "Monitorear. Si supera 72h sin confirmación, escalar a tesorería.",
+    },
+    [RemittanceExceptionCode_1.RemittanceExceptionCode.INPROCESS_STALE_24H]: {
+        motivo: "La transacción lleva más de 24h sin avanzar a PAYABLE/PAID.",
+        accionSugerida: "Verificar el sync con el proveedor. Si no responde, escalar a soporte con el número de transacción.",
+    },
+    [RemittanceExceptionCode_1.RemittanceExceptionCode.UNKNOWN]: {
+        motivo: "Situación no catalogada.",
+        accionSugerida: "Revisar manualmente el detalle de la transacción y escalar si aplica.",
+    },
+};
+/**
+ * Mapa de códigos CRUDOS de UNIR (sub-status) → our-code.
+ * Se amplía minando el PDF de UNIR (tarea aparte). Las claves se normalizan a MAYÚSCULAS.
+ */
+const UNIR_HOLD_SUBSTATUS_TO_CODE = {
+    SENDMONEY_TIMEOUT: RemittanceExceptionCode_1.RemittanceExceptionCode.HOLD_PROVIDER_TIMEOUT,
+    TIMEOUT: RemittanceExceptionCode_1.RemittanceExceptionCode.HOLD_PROVIDER_TIMEOUT,
+    DISPERSAL_UNCONFIRMED: RemittanceExceptionCode_1.RemittanceExceptionCode.HOLD_DISPERSAL_UNCONFIRMED,
+    COMPLIANCE_REVIEW: RemittanceExceptionCode_1.RemittanceExceptionCode.HOLD_COMPLIANCE_REVIEW,
+};
+/**
+ * Mapa de cancelReason → our-code.
+ * Incluye tanto los valores reales de RemittanceCancelledByEnum (USER / SYSTEM)
+ * como los códigos semánticos de UNIR (USER_REQUESTED / PROVIDER_INITIATED).
+ */
+const UNIR_CANCEL_REASON_TO_CODE = {
+    // Valores de RemittanceCancelledByEnum
+    USER: RemittanceExceptionCode_1.RemittanceExceptionCode.CANCEL_USER_REQUESTED,
+    SYSTEM: RemittanceExceptionCode_1.RemittanceExceptionCode.CANCEL_GENERIC,
+    // Códigos semánticos de UNIR
+    USER_REQUESTED: RemittanceExceptionCode_1.RemittanceExceptionCode.CANCEL_USER_REQUESTED,
+    PROVIDER_INITIATED: RemittanceExceptionCode_1.RemittanceExceptionCode.CANCEL_PROVIDER_INITIATED,
+};
+/**
+ * Resuelve el our-code a partir del status + los códigos crudos de UNIR.
+ * Fallback por bucket (HOLD_GENERIC / CANCEL_GENERIC / INPROCESS_STALE_24H) y
+ * UNKNOWN para status inesperados. Nunca lanza.
+ */
+function resolveExceptionCode(status, unirSubStatus, cancelReason) {
+    switch (status) {
+        case "HOLD": {
+            const key = (unirSubStatus ?? "").trim().toUpperCase();
+            return UNIR_HOLD_SUBSTATUS_TO_CODE[key] ?? RemittanceExceptionCode_1.RemittanceExceptionCode.HOLD_GENERIC;
+        }
+        case "CANCELLATION_IN_PROGRESS": {
+            const key = (cancelReason ?? "").trim().toUpperCase();
+            return UNIR_CANCEL_REASON_TO_CODE[key] ?? RemittanceExceptionCode_1.RemittanceExceptionCode.CANCEL_GENERIC;
+        }
+        case "IN_PROCESS":
+            return RemittanceExceptionCode_1.RemittanceExceptionCode.INPROCESS_STALE_24H;
+        default:
+            return RemittanceExceptionCode_1.RemittanceExceptionCode.UNKNOWN;
+    }
+}

package/bin/remittance/dtos/index.d.ts

@@ -44,3 +44,4 @@ export * from "./RemittancePricing";
 export * from "./RemittancePromotion";
 export * from "./RemittanceRule";
 export * from "./RemittancePricingTable";
+export * from "./RemittanceExceptionCatalog";

package/bin/remittance/dtos/index.js

@@ -60,3 +60,4 @@ __exportStar(require("./RemittancePricing"), exports);
 __exportStar(require("./RemittancePromotion"), exports);
 __exportStar(require("./RemittanceRule"), exports);
 __exportStar(require("./RemittancePricingTable"), exports);
+__exportStar(require("./RemittanceExceptionCatalog"), exports);

package/bin/remittance/enums/RemittanceExceptionCode.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Códigos propios ("our-code") de excepciones de remesas. Traducimos los códigos
+ * crudos de UNIR a ESTE formato; los crudos NUNCA se exponen. UNKNOWN es el
+ * fallback para sub-status/motivos no catalogados (nuevos o desconocidos).
+ */
+export declare enum RemittanceExceptionCode {
+    HOLD_DISPERSAL_UNCONFIRMED = "HOLD_DISPERSAL_UNCONFIRMED",
+    HOLD_PROVIDER_TIMEOUT = "HOLD_PROVIDER_TIMEOUT",
+    HOLD_COMPLIANCE_REVIEW = "HOLD_COMPLIANCE_REVIEW",
+    HOLD_GENERIC = "HOLD_GENERIC",
+    CANCEL_USER_REQUESTED = "CANCEL_USER_REQUESTED",
+    CANCEL_PROVIDER_INITIATED = "CANCEL_PROVIDER_INITIATED",
+    CANCEL_GENERIC = "CANCEL_GENERIC",
+    INPROCESS_STALE_24H = "INPROCESS_STALE_24H",
+    UNKNOWN = "UNKNOWN"
+}

package/bin/remittance/enums/RemittanceExceptionCode.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RemittanceExceptionCode = void 0;
+/**
+ * Códigos propios ("our-code") de excepciones de remesas. Traducimos los códigos
+ * crudos de UNIR a ESTE formato; los crudos NUNCA se exponen. UNKNOWN es el
+ * fallback para sub-status/motivos no catalogados (nuevos o desconocidos).
+ */
+var RemittanceExceptionCode;
+(function (RemittanceExceptionCode) {
+    // HOLD (el proveedor marcó la tx)
+    RemittanceExceptionCode["HOLD_DISPERSAL_UNCONFIRMED"] = "HOLD_DISPERSAL_UNCONFIRMED";
+    RemittanceExceptionCode["HOLD_PROVIDER_TIMEOUT"] = "HOLD_PROVIDER_TIMEOUT";
+    RemittanceExceptionCode["HOLD_COMPLIANCE_REVIEW"] = "HOLD_COMPLIANCE_REVIEW";
+    RemittanceExceptionCode["HOLD_GENERIC"] = "HOLD_GENERIC";
+    // Cancelación en proceso
+    RemittanceExceptionCode["CANCEL_USER_REQUESTED"] = "CANCEL_USER_REQUESTED";
+    RemittanceExceptionCode["CANCEL_PROVIDER_INITIATED"] = "CANCEL_PROVIDER_INITIATED";
+    RemittanceExceptionCode["CANCEL_GENERIC"] = "CANCEL_GENERIC";
+    // In-process atorada > 24h
+    RemittanceExceptionCode["INPROCESS_STALE_24H"] = "INPROCESS_STALE_24H";
+    // Fallback
+    RemittanceExceptionCode["UNKNOWN"] = "UNKNOWN";
+})(RemittanceExceptionCode || (exports.RemittanceExceptionCode = RemittanceExceptionCode = {}));

package/bin/remittance/enums/index.d.ts

@@ -22,3 +22,4 @@ export * from "./RuleField";
 export * from "./RuleOperator";
 export * from "./RuleActionType";
 export * from "./AuditResult";
+export * from "./RemittanceExceptionCode";

package/bin/remittance/enums/index.js

@@ -38,3 +38,4 @@ __exportStar(require("./RuleField"), exports);
 __exportStar(require("./RuleOperator"), exports);
 __exportStar(require("./RuleActionType"), exports);
 __exportStar(require("./AuditResult"), exports);
+__exportStar(require("./RemittanceExceptionCode"), exports);

package/bin/walletFunding/dtos/CancelFundingReferenceRequest.d.ts

@@ -1,6 +1,5 @@
 export declare class CancelFundingReferenceRequest {
-    /** Referencia Passport (PK de EqualityFundingReference_GT). */
-    reference: string;
+    fundingId: string;
     directoryId: string;
     idempotencyKey: string;
 }

package/bin/walletFunding/dtos/CancelFundingReferenceRequest.js

@@ -18,7 +18,7 @@ __decorate([
     (0, class_validator_1.IsString)(),
     (0, class_validator_1.MaxLength)(64),
     __metadata("design:type", String)
-], CancelFundingReferenceRequest.prototype, "reference", void 0);
+], CancelFundingReferenceRequest.prototype, "fundingId", void 0);
 __decorate([
     (0, class_validator_1.IsString)(),
     (0, class_validator_1.MaxLength)(64),

package/bin/walletFunding/dtos/CancelFundingReferenceResponse.d.ts

@@ -1,7 +1,7 @@
 import { BenefitPaymentStatusEnum } from "../../benefitCenter/enums/BenefitPaymentStatusEnum";
 import { WalletFundingErrorCodeEnum } from "../enums/WalletFundingErrorCodeEnum";
 export declare class CancelFundingReferenceResponse {
-    reference: string;
+    fundingId: string;
     status: BenefitPaymentStatusEnum;
     errorCode?: WalletFundingErrorCodeEnum;
 }

package/bin/walletFunding/dtos/CancelFundingRequest.d.ts

@@ -1,6 +1,6 @@
 /**
  * Request del cancel via Centro de Beneficios (spec 13 v2.0).
- * `reference` viaja en el path, `directoryId` se resuelve del JWT.
+ * `fundingId` viaja en el path, `directoryId` se resuelve del JWT.
  * `providerModuleName` permite al marketplace rutear al publisher correcto
  * sin tener que persistir el mapping (el wallet-app sabe el moduleName
  * porque vino en la respuesta del authorize).

package/bin/walletFunding/dtos/CancelFundingRequest.js

@@ -13,7 +13,7 @@ exports.CancelFundingRequest = void 0;
 const class_validator_1 = require("class-validator");
 /**
  * Request del cancel via Centro de Beneficios (spec 13 v2.0).
- * `reference` viaja en el path, `directoryId` se resuelve del JWT.
+ * `fundingId` viaja en el path, `directoryId` se resuelve del JWT.
  * `providerModuleName` permite al marketplace rutear al publisher correcto
  * sin tener que persistir el mapping (el wallet-app sabe el moduleName
  * porque vino en la respuesta del authorize).

package/bin/walletFunding/dtos/CancelFundingResponse.d.ts

@@ -7,7 +7,7 @@ import { WalletFundingErrorCodeEnum } from "../enums/WalletFundingErrorCodeEnum"
  * (marketplace ↔ connector). Idempotente: re-cancelar devuelve APPROVED.
  */
 export declare class CancelFundingResponse {
-    reference: string;
+    fundingId: string;
     status: BenefitPaymentStatusEnum;
     errorCode?: WalletFundingErrorCodeEnum;
     message?: string;

package/bin/walletFunding/dtos/CancelWalletFundingResponse.d.ts

@@ -3,5 +3,5 @@ import { WalletFundingErrorCodeEnum } from "../enums/WalletFundingErrorCodeEnum"
 export declare class CancelWalletFundingResponse {
     status: BenefitPaymentStatusEnum;
     errorCode?: WalletFundingErrorCodeEnum;
-    reference?: string;
+    fundingId?: string;
 }

package/package.json

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

package/src/remittance/dtos/RemittanceExceptionCatalog.ts

@@ -0,0 +1,97 @@
+import { RemittanceExceptionCode } from "../enums/RemittanceExceptionCode";
+
+export interface ExceptionCatalogEntry {
+    motivo: string;
+    accionSugerida: string;
+}
+
+/** our-code → texto ya traducido (español). El front lo muestra tal cual. */
+export const REMITTANCE_EXCEPTION_CATALOG: Record<RemittanceExceptionCode, ExceptionCatalogEntry> = {
+    [RemittanceExceptionCode.HOLD_DISPERSAL_UNCONFIRMED]: {
+        motivo: "El proveedor no ha confirmado la dispersión de fondos.",
+        accionSugerida: "Investigar el estado de la dispersión. Si supera 48h en HOLD, escalar a soporte del proveedor.",
+    },
+    [RemittanceExceptionCode.HOLD_PROVIDER_TIMEOUT]: {
+        motivo: "Tiempo de espera agotado con el proveedor · sin confirmar dispersión.",
+        accionSugerida: "Investigar el estado de la transacción. Si supera 48h en HOLD, escalar a soporte del proveedor.",
+    },
+    [RemittanceExceptionCode.HOLD_COMPLIANCE_REVIEW]: {
+        motivo: "El proveedor puso la transacción en revisión de cumplimiento.",
+        accionSugerida: "Monitorear. Si el proveedor no libera en 72h, escalar a soporte.",
+    },
+    [RemittanceExceptionCode.HOLD_GENERIC]: {
+        motivo: "El proveedor marcó la transacción con un problema.",
+        accionSugerida: "Investigar el estado de la transacción. Si supera 48h en HOLD, escalar a soporte del proveedor.",
+    },
+    [RemittanceExceptionCode.CANCEL_USER_REQUESTED]: {
+        motivo: "El cliente canceló la transacción. Esperando que el proveedor confirme la devolución de fondos.",
+        accionSugerida: "Monitorear. La devolución al monedero se dispara automáticamente al confirmar el proveedor. Si supera 72h, escalar a tesorería.",
+    },
+    [RemittanceExceptionCode.CANCEL_PROVIDER_INITIATED]: {
+        motivo: "El proveedor inició la cancelación de la transacción.",
+        accionSugerida: "Monitorear la confirmación de devolución. Si supera 72h, escalar a tesorería.",
+    },
+    [RemittanceExceptionCode.CANCEL_GENERIC]: {
+        motivo: "Cancelación en proceso. Esperando confirmación del proveedor.",
+        accionSugerida: "Monitorear. Si supera 72h sin confirmación, escalar a tesorería.",
+    },
+    [RemittanceExceptionCode.INPROCESS_STALE_24H]: {
+        motivo: "La transacción lleva más de 24h sin avanzar a PAYABLE/PAID.",
+        accionSugerida: "Verificar el sync con el proveedor. Si no responde, escalar a soporte con el número de transacción.",
+    },
+    [RemittanceExceptionCode.UNKNOWN]: {
+        motivo: "Situación no catalogada.",
+        accionSugerida: "Revisar manualmente el detalle de la transacción y escalar si aplica.",
+    },
+};
+
+/**
+ * Mapa de códigos CRUDOS de UNIR (sub-status) → our-code.
+ * Se amplía minando el PDF de UNIR (tarea aparte). Las claves se normalizan a MAYÚSCULAS.
+ */
+const UNIR_HOLD_SUBSTATUS_TO_CODE: Record<string, RemittanceExceptionCode> = {
+    SENDMONEY_TIMEOUT: RemittanceExceptionCode.HOLD_PROVIDER_TIMEOUT,
+    TIMEOUT: RemittanceExceptionCode.HOLD_PROVIDER_TIMEOUT,
+    DISPERSAL_UNCONFIRMED: RemittanceExceptionCode.HOLD_DISPERSAL_UNCONFIRMED,
+    COMPLIANCE_REVIEW: RemittanceExceptionCode.HOLD_COMPLIANCE_REVIEW,
+};
+
+/**
+ * Mapa de cancelReason → our-code.
+ * Incluye tanto los valores reales de RemittanceCancelledByEnum (USER / SYSTEM)
+ * como los códigos semánticos de UNIR (USER_REQUESTED / PROVIDER_INITIATED).
+ */
+const UNIR_CANCEL_REASON_TO_CODE: Record<string, RemittanceExceptionCode> = {
+    // Valores de RemittanceCancelledByEnum
+    USER: RemittanceExceptionCode.CANCEL_USER_REQUESTED,
+    SYSTEM: RemittanceExceptionCode.CANCEL_GENERIC,
+    // Códigos semánticos de UNIR
+    USER_REQUESTED: RemittanceExceptionCode.CANCEL_USER_REQUESTED,
+    PROVIDER_INITIATED: RemittanceExceptionCode.CANCEL_PROVIDER_INITIATED,
+};
+
+/**
+ * Resuelve el our-code a partir del status + los códigos crudos de UNIR.
+ * Fallback por bucket (HOLD_GENERIC / CANCEL_GENERIC / INPROCESS_STALE_24H) y
+ * UNKNOWN para status inesperados. Nunca lanza.
+ */
+export function resolveExceptionCode(
+    status: string,
+    unirSubStatus?: string | null,
+    cancelReason?: string | null,
+): RemittanceExceptionCode {
+    switch (status) {
+        case "HOLD": {
+            const key = (unirSubStatus ?? "").trim().toUpperCase();
+            return UNIR_HOLD_SUBSTATUS_TO_CODE[key] ?? RemittanceExceptionCode.HOLD_GENERIC;
+        }
+        case "CANCELLATION_IN_PROGRESS": {
+            const key = (cancelReason ?? "").trim().toUpperCase();
+            return UNIR_CANCEL_REASON_TO_CODE[key] ?? RemittanceExceptionCode.CANCEL_GENERIC;
+        }
+        case "IN_PROCESS":
+            return RemittanceExceptionCode.INPROCESS_STALE_24H;
+        default:
+            return RemittanceExceptionCode.UNKNOWN;
+    }
+}

package/src/remittance/dtos/index.ts

@@ -44,3 +44,4 @@ export * from "./RemittancePricing";
 export * from "./RemittancePromotion";
 export * from "./RemittanceRule";
 export * from "./RemittancePricingTable";
+export * from "./RemittanceExceptionCatalog";

package/src/remittance/enums/RemittanceExceptionCode.ts

@@ -0,0 +1,20 @@
+/**
+ * Códigos propios ("our-code") de excepciones de remesas. Traducimos los códigos
+ * crudos de UNIR a ESTE formato; los crudos NUNCA se exponen. UNKNOWN es el
+ * fallback para sub-status/motivos no catalogados (nuevos o desconocidos).
+ */
+export enum RemittanceExceptionCode {
+    // HOLD (el proveedor marcó la tx)
+    HOLD_DISPERSAL_UNCONFIRMED = "HOLD_DISPERSAL_UNCONFIRMED",
+    HOLD_PROVIDER_TIMEOUT = "HOLD_PROVIDER_TIMEOUT",
+    HOLD_COMPLIANCE_REVIEW = "HOLD_COMPLIANCE_REVIEW",
+    HOLD_GENERIC = "HOLD_GENERIC",
+    // Cancelación en proceso
+    CANCEL_USER_REQUESTED = "CANCEL_USER_REQUESTED",
+    CANCEL_PROVIDER_INITIATED = "CANCEL_PROVIDER_INITIATED",
+    CANCEL_GENERIC = "CANCEL_GENERIC",
+    // In-process atorada > 24h
+    INPROCESS_STALE_24H = "INPROCESS_STALE_24H",
+    // Fallback
+    UNKNOWN = "UNKNOWN",
+}

package/src/remittance/enums/index.ts

@@ -22,3 +22,4 @@ export * from "./RuleField";
 export * from "./RuleOperator";
 export * from "./RuleActionType";
 export * from "./AuditResult";
+export * from "./RemittanceExceptionCode";