@fiado/type-kit 3.218.0 → 3.220.0

package/src/kyc/helpers/applyKycStep.ts

@@ -0,0 +1,36 @@
+import { KycSubChecks } from '../dtos/KycSubChecks';
+import { KycSubCheckNameEnum } from '../enums/KycSubCheckNameEnum';
+import { KycSubCheckStatusEnum } from '../enums/KycSubCheckStatusEnum';
+import { KycWatchlistStatusEnum } from '../enums/KycWatchlistStatusEnum';
+
+/**
+ * Asienta el resultado de UNA estación (`KycStepCompletedV1`) sobre el progreso acumulado de la
+ * verificación, y devuelve un objeto NUEVO — no muta el que recibe.
+ *
+ * **Por qué esto vive en la lib y no en cada consumidor:** la asignación obvia
+ * `progreso[evento.step] = evento.status` **no compila**. Todos los campos de `KycSubChecks` son
+ * opcionales, así que al escribir a través de una llave-unión TypeScript exige el tipo intersección
+ * de todas las propiedades, que colapsa a `undefined` (TS2322). El consumidor que se topa con eso
+ * lo resuelve con `(progreso as Record<string, string>)[step] = status`, y ese cast desactiva
+ * justamente el cruce estación ↔ vocabulario que `IsKycStepStatusByStep` acaba de defender: un
+ * `watchlists: 'FAIL'` armado en memoria ya no lo detiene nadie.
+ *
+ * Concentrar el cast acá lo deja en UN solo lugar auditado, en vez de replicado en cada repo que
+ * consuma el evento. La seguridad real viene de haber validado el evento en el boundary; este helper
+ * solo evita que cada consumidor reinvente el atajo inseguro.
+ *
+ * ⚠️ NO valida la coherencia estación ↔ status: eso ya lo hizo el DTO en el boundary. Si se le pasa
+ * un par incoherente a mano, lo escribe — igual que lo haría el cast que reemplaza.
+ *
+ * SureKeep Fase 2 — progreso del KYC estación por estación.
+ */
+export function applyKycStep(
+    progreso: KycSubChecks | undefined,
+    step: KycSubCheckNameEnum,
+    status: KycSubCheckStatusEnum | KycWatchlistStatusEnum,
+): KycSubChecks {
+    // El único cast del ecosistema para escribir por llave dinámica sobre `KycSubChecks`.
+    const siguiente = { ...(progreso ?? {}) } as Record<string, string>;
+    siguiente[step] = status;
+    return siguiente as KycSubChecks;
+}

package/src/kyc/index.ts

@@ -3,10 +3,17 @@
 export * from './enums/KycVerificationStatusEnum';
 export * from './enums/KycSubCheckStatusEnum';
 export * from './enums/KycWatchlistStatusEnum';
+export * from './enums/KycSubCheckNameEnum';
 
 // Sub-pasos descompuestos (SureKeep F2)
 export * from './dtos/KycSubChecks';
 
+// Validators
+export * from './validators/IsKycStepStatusByStep';
+
+// Helpers
+export * from './helpers/applyKycStep';
+
 // Domicilio del INE normalizado por places (SureKeep F2)
 export * from './dtos/KycAddress';
 
@@ -16,3 +23,4 @@ export * from './dtos/responses/KycByDirectoryResponse';
 
 // Events
 export * from './events/KycVerificationChangedV1';
+export * from './events/KycStepCompletedV1';

package/src/kyc/validators/IsKycStepStatusByStep.ts

@@ -0,0 +1,57 @@
+import { ValidatorConstraint, ValidatorConstraintInterface, ValidationArguments } from 'class-validator';
+import { KycSubCheckNameEnum, KYC_WATCHLIST_STEPS } from '../enums/KycSubCheckNameEnum';
+import { KycSubCheckStatusEnum } from '../enums/KycSubCheckStatusEnum';
+import { KycWatchlistStatusEnum } from '../enums/KycWatchlistStatusEnum';
+
+const VALORES_LISTA: readonly string[] = Object.values(KycWatchlistStatusEnum);
+const VALORES_BINARIO: readonly string[] = Object.values(KycSubCheckStatusEnum);
+
+/**
+ * Valida que el `status` de un `KycStepCompletedV1` pertenezca al vocabulario de SU estación:
+ * las de lista hablan `CLEAR`/`HIT`, las binarias `PASS`/`FAIL`.
+ *
+ * **Por qué un validador y no un `@IsIn` con los cuatro valores:** un `@IsIn(['PASS','FAIL','CLEAR','HIT'])`
+ * aceptaría `{ step: 'watchlists', status: 'FAIL' }`. Eso rompe el matiz que `KycWatchlistStatusEnum`
+ * existe para proteger — un HIT **no es un fallo**, es "que lo mire cumplimiento". Con ese evento
+ * colado, el consumidor lo escribiría en el progreso y la pantalla del vendedor marcaría como falla
+ * algo que solo requiere revisión. El candado del anidado (`KycSubChecks`) tiene que valer igual
+ * cuando la estación viaja suelta.
+ *
+ * Es la misma razón por la que `KycSubChecks` tipa cada campo a su enum en vez de a un string.
+ *
+ * Uso:
+ * ```ts
+ *   @Validate(IsKycStepStatusByStep)
+ *   status!: KycSubCheckStatusEnum | KycWatchlistStatusEnum;
+ * ```
+ *
+ * SureKeep Fase 2 — progreso del KYC estación por estación.
+ */
+@ValidatorConstraint({ name: 'IsKycStepStatusByStep', async: false })
+export class IsKycStepStatusByStep implements ValidatorConstraintInterface {
+    validate(value: unknown, args: ValidationArguments): boolean {
+        if (typeof value !== 'string') return false;
+
+        const step = (args.object as { step?: unknown }).step;
+
+        // Un `step` fuera del enum ya falla por su propio `@IsEnum`. Acá se rechaza igual en vez de
+        // dejar pasar el status: sin estación conocida no hay vocabulario contra el cual validar.
+        if (!Object.values(KycSubCheckNameEnum).includes(step as KycSubCheckNameEnum)) return false;
+
+        return KYC_WATCHLIST_STEPS.includes(step as KycSubCheckNameEnum)
+            ? VALORES_LISTA.includes(value)
+            : VALORES_BINARIO.includes(value);
+    }
+
+    defaultMessage(args: ValidationArguments): string {
+        const step = (args.object as { step?: unknown }).step;
+
+        if (KYC_WATCHLIST_STEPS.includes(step as KycSubCheckNameEnum)) {
+            return `status de la estación ${String(step)} debe ser ${VALORES_LISTA.join(' o ')} (un HIT no es un fallo)`;
+        }
+        if (Object.values(KycSubCheckNameEnum).includes(step as KycSubCheckNameEnum)) {
+            return `status de la estación ${String(step)} debe ser ${VALORES_BINARIO.join(' o ')}`;
+        }
+        return 'status no se puede validar sin un step reconocido';
+    }
+}

package/src/retailWizard/dtos/responses/KycPrepareResponse.ts

@@ -23,6 +23,12 @@ export interface KycSdkMetadata {
     phoneNumber: string;
     typeOfDocumentId?: string;
     isPartial?: boolean;
+    /**
+     * Idioma con el que Metamap fija el flujo del widget. El wizard lo manda como `'es'` para que
+     * la verificación salga en español por defecto (si no viaja, Metamap arranca en su default, inglés).
+     * Va opcional en el tipo porque es un ajuste de presentación del SDK, no parte de la correlación.
+     */
+    fixedLanguage?: string;
     customInput?: boolean;
     userPhotoLink?: string;
     userPhotoLinkHash?: string;