@fiado/type-kit 3.252.0 → 3.254.0

package/src/biometrics/dtos/responses/BiometricVerificationResponse.ts

@@ -0,0 +1,133 @@
+import { Expose } from 'class-transformer';
+import {
+    IsEnum,
+    IsISO8601,
+    IsNotEmpty,
+    IsNumber,
+    IsOptional,
+    IsString,
+    Max,
+    MaxLength,
+    Min,
+} from 'class-validator';
+import { BiometricDeliveryModeEnum } from '../../enums/BiometricDeliveryModeEnum';
+import { BiometricProviderEnum } from '../../enums/BiometricProviderEnum';
+import { BiometricResultEnum } from '../../enums/BiometricResultEnum';
+import { BiometricTypeEnum } from '../../enums/BiometricTypeEnum';
+import { BiometricVerificationStatusEnum } from '../../enums/BiometricVerificationStatusEnum';
+import type { BiometricDelivery } from '../BiometricDelivery';
+
+/**
+ * El estado completo de una verificación biométrica.
+ *
+ * 🔴 **El MISMO tipo lo devuelven el `POST` y el `GET`** (DEC-012). Es una excepción consciente a
+ * "1 DTO por endpoint": el `POST` devuelve el estado inicial del MISMO recurso que el `GET` expone
+ * después. Duplicar el tipo garantizaría drift entre los dos — la clase de bug donde el `GET` gana
+ * un campo y el `POST` no, y el caller descubre la diferencia en producción. Queda registrado acá
+ * para que no haya que re-discutirlo en cada PR.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export class BiometricVerificationResponse {
+    /**
+     * La llave de todo. Se genera al crear, viaja dentro de la metadata del proveedor, y vuelve
+     * ECOADA en cada webhook — **por eso la correlación es un `get` por PK y no una búsqueda**.
+     */
+    @Expose() @IsString() @IsNotEmpty()
+    biometricVerificationId!: string;
+
+    /** Eco de lo que pediste. */
+    @Expose() @IsEnum(BiometricTypeEnum)
+    type!: BiometricTypeEnum;
+
+    /** Eco de lo que pediste. */
+    @Expose() @IsEnum(BiometricProviderEnum)
+    provider!: BiometricProviderEnum;
+
+    /** Eco de lo que pediste. */
+    @Expose() @IsString() @IsNotEmpty()
+    directoryId!: string;
+
+    /** Dónde va el PROCESO. Ver `BiometricVerificationStatusEnum`. */
+    @Expose() @IsEnum(BiometricVerificationStatusEnum)
+    status!: BiometricVerificationStatusEnum;
+
+    /**
+     * Qué dijo el BIOMÉTRICO. Ver `BiometricResultEnum`.
+     *
+     * ⚠️ Puede venir poblado con `status` todavía en `IN_PROGRESS`: el veredicto del facematch llega
+     * en el `step_completed`, antes del cierre de la verificación. Eso no es una inconsistencia, es
+     * exactamente la razón de que `status` y `result` sean campos distintos.
+     */
+    @Expose() @IsEnum(BiometricResultEnum)
+    result!: BiometricResultEnum;
+
+    /** Discriminador de `delivery`. Ver `BiometricDeliveryModeEnum`. */
+    @Expose() @IsEnum(BiometricDeliveryModeEnum)
+    deliveryMode!: BiometricDeliveryModeEnum;
+
+    /**
+     * Lo que necesitas para ejecutar el biométrico. Su forma depende de `deliveryMode` — haz el
+     * `switch`, no leas `link` a ciegas.
+     *
+     * Sin decorador de validación a propósito: es una unión discriminada y `class-validator` no
+     * sabe validar uniones sin un `@Type()` con discriminador que acá agregaría más ceremonia que
+     * seguridad. El contrato lo garantiza el productor, que es un solo lambda.
+     */
+    @Expose()
+    delivery!: BiometricDelivery;
+
+    /**
+     * Similitud reportada por el proveedor, 0–100, cuando la expone. Rekognition da score; Metamap
+     * responde pass/fail y esto viene ausente.
+     *
+     * ⚠️ **No lo uses para decidir tú el umbral.** El proveedor ya aplicó el suyo y eso es lo que
+     * dice `result`. Esto es para diagnóstico y para calibrar, no para re-juzgar.
+     */
+    @Expose() @IsOptional() @IsNumber() @Min(0) @Max(100)
+    score?: number;
+
+    /** Umbral que aplicó el proveedor, cuando lo expone. Contexto para leer el `score`. */
+    @Expose() @IsOptional() @IsNumber() @Min(0) @Max(100)
+    threshold?: number;
+
+    /**
+     * El id de la verificación del lado del proveedor (en Metamap, su `verificationId`). Para
+     * soporte y reconciliación: es lo que se busca en el panel del proveedor.
+     */
+    @Expose() @IsOptional() @IsString() @IsNotEmpty()
+    providerRef?: string;
+
+    /** Tu correlación, tal cual la mandaste. */
+    @Expose() @IsOptional() @IsString() @MaxLength(256)
+    callerContext?: string;
+
+    /**
+     * Por qué falló, solo con `status = FAILED`. Texto OPERACIONAL, sin PII y sin nada del
+     * proveedor: describe qué se rompió de nuestro lado (DEC-013).
+     */
+    @Expose() @IsOptional() @IsString()
+    failureReason?: string;
+
+    /**
+     * Todas las marcas de tiempo son **`string` ISO-8601 UTC con `Z`**.
+     *
+     * ⚠️ En la tabla se persisten como `Number` (dynamoose serializa `Date` a number, y un GSI
+     * declarado `S` sobre un timestamp se rompe en silencio). El mapeo Row → DTO es explícito. Si
+     * copias este tipo para el `Row`, rompes el índice.
+     */
+    @Expose() @IsISO8601({ strict: true })
+    createdAt!: string;
+
+    /** Última vez que cambió algo. ISO-8601 UTC con `Z`. */
+    @Expose() @IsISO8601({ strict: true })
+    updatedAt!: string;
+
+    /** Cuándo vence la entrega. Es lo que el `GET` compara para persistir `EXPIRED` (DEC-015). */
+    @Expose() @IsISO8601({ strict: true })
+    expiresAt!: string;
+
+    /** Cuándo alcanzó un estado terminal. Ausente mientras siga viva. */
+    @Expose() @IsOptional() @IsISO8601({ strict: true })
+    completedAt?: string;
+}

package/src/biometrics/enums/BiometricDeliveryModeEnum.ts

@@ -0,0 +1,31 @@
+/**
+ * CÓMO se le entrega al caller lo que necesita para ejecutar el biométrico. **Es el discriminador
+ * de `BiometricVerificationResponse.delivery`.**
+ *
+ * 🔴 **Esta es la pieza que hace genérico al contrato, y la razón de que exista este servicio.**
+ * Los proveedores no se parecen en nada:
+ *
+ * | Proveedor | Qué entrega | Quién ejecuta | Cómo vuelve el resultado |
+ * |---|---|---|---|
+ * | Metamap  | un link hospedado | el navegador del usuario | webhook async |
+ * | Apple/Google | un challenge + nonce | el dispositivo, on-device | attestation que devuelve el cliente |
+ * | Amazon   | nada (se mandan imágenes) | nuestro servidor | síncrono, con score |
+ *
+ * Si la respuesta fuera `{ link }` a secas, **solo Metamap entraría** y el día que llegue Apple
+ * habría que romper el contrato con todos los callers ya escritos. Discriminar por el MODO —y no
+ * por el proveedor— deja que entre cualquiera de los tres sin tocar a nadie.
+ *
+ * El `GET` de polling NO cambia entre modos: devuelve estado, no mecanismo.
+ *
+ * `biometrics-business` — Entrega 1 (solo `REDIRECT` produce valores reales).
+ */
+export enum BiometricDeliveryModeEnum {
+    /** `delivery` trae `{ link, expiresAt }`. El usuario abre el link y ejecuta ahí. */
+    REDIRECT = 'REDIRECT',
+
+    /** `delivery` trae `{ challenge, nonce, expiresAt }`. El dispositivo firma y devuelve. */
+    CHALLENGE = 'CHALLENGE',
+
+    /** `delivery` viene vacío: el biométrico ya corrió y `result` viene poblado en la misma respuesta. */
+    IMMEDIATE = 'IMMEDIATE',
+}

package/src/biometrics/enums/BiometricEventTypeEnum.ts

@@ -0,0 +1,31 @@
+/**
+ * Qué le pasó a la verificación, según el proveedor. Viaja en `BiometricVerificationChangedV1` y es
+ * lo que el consumer usa para decidir la transición de estado.
+ *
+ * Es el vocabulario NUESTRO, no el de Metamap: `kyc-metamap-webhook` traduce sus `eventName` a
+ * estos cuatro antes de publicar. Así el consumer no aprende el catálogo de un proveedor externo, y
+ * el día que entre otro proveedor traduce a los mismos cuatro.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export enum BiometricEventTypeEnum {
+    /** El usuario arrancó la verificación. → `IN_PROGRESS`. */
+    VERIFICATION_STARTED = 'VERIFICATION_STARTED',
+
+    /**
+     * Cerró una estación con resultado. Es el que trae el veredicto del facematch, ANTES del cierre:
+     * por eso `result` puede quedar poblado con `status` todavía en `IN_PROGRESS`.
+     */
+    STEP_COMPLETED = 'STEP_COMPLETED',
+
+    /** El proveedor cerró la verificación. → `COMPLETED`. */
+    VERIFICATION_COMPLETED = 'VERIFICATION_COMPLETED',
+
+    /**
+     * El proveedor la dio por vencida. → `EXPIRED`.
+     *
+     * ⚠️ **No se depende de este evento para expirar.** El `GET` persiste `EXPIRED` comparando
+     * contra `expiresAt` (DEC-015), así que una verificación vence aunque este evento nunca llegue.
+     */
+    VERIFICATION_EXPIRED = 'VERIFICATION_EXPIRED',
+}

package/src/biometrics/enums/BiometricProviderEnum.ts

@@ -0,0 +1,28 @@
+/**
+ * QUIÉN ejecuta el biométrico. Ortogonal a `BiometricTypeEnum`: el mismo `FACEMATCH` lo puede
+ * resolver Metamap con un link o Amazon con una llamada síncrona.
+ *
+ * 🔴 **Es OBLIGATORIO en el request** (DEC-004, decisión de Andres 2026-07-30). El caller nombra al
+ * proveedor en vez de dejar que `biometrics-business` resuelva un default.
+ *
+ * **Consecuencia registrada (TD-001):** cambiar de proveedor obliga a tocar y redesplegar a TODOS
+ * los callers. Se aceptó a cambio de que la elección sea explícita y auditable en cada request.
+ *
+ * Solo `METAMAP` está implementado. Los otros tres cambian el MODO DE ENTREGA, no solo el
+ * proveedor — por eso existe `BiometricDeliveryModeEnum`.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export enum BiometricProviderEnum {
+    /** El único implementado. Entrega por link hospedado + webhook async → `REDIRECT`. */
+    METAMAP = 'METAMAP',
+
+    /** Face ID, on-device. Entregaría un challenge y recibiría una attestation → `CHALLENGE`. */
+    APPLE = 'APPLE',
+
+    /** Biometría de Android, on-device. Mismo modo que Apple → `CHALLENGE`. */
+    GOOGLE = 'GOOGLE',
+
+    /** Rekognition: comparación en servidor, con score. Respuesta síncrona → `IMMEDIATE`. */
+    AWS = 'AWS',
+}

package/src/biometrics/enums/BiometricResultEnum.ts

@@ -0,0 +1,28 @@
+/**
+ * Qué dijo el BIOMÉTRICO. Ortogonal a `BiometricVerificationStatusEnum`, que dice dónde va el
+ * proceso — ver el comentario de ese enum para por qué van separados.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export enum BiometricResultEnum {
+    /**
+     * Todavía no hay veredicto. Es el valor inicial y también el de los terminales que cierran sin
+     * resultado (`EXPIRED`, `FAILED`).
+     *
+     * ⚠️ `UNKNOWN` **no es** `NO_MATCH`. Tratarlos igual convierte "el usuario nunca abrió el link"
+     * en "el usuario no es quien dice ser" — que es una acusación, no un dato.
+     */
+    UNKNOWN = 'UNKNOWN',
+
+    /** Coincide con la referencia. En Metamap: el step `facematch-service-validation` sin `error`. */
+    MATCH = 'MATCH',
+
+    /** No coincide. Es un veredicto real del proveedor, no una falla de proceso. */
+    NO_MATCH = 'NO_MATCH',
+
+    /**
+     * El biométrico corrió pero no concluye (mala iluminación, foto de referencia pobre, score en la
+     * zona gris). Distinto de `UNKNOWN`: acá sí hubo intento.
+     */
+    INCONCLUSIVE = 'INCONCLUSIVE',
+}

package/src/biometrics/enums/BiometricTypeEnum.ts

@@ -0,0 +1,23 @@
+/**
+ * QUÉ biométrico se pide. Es el discriminador del caso de uso, independiente de quién lo ejecute
+ * (eso lo dice `BiometricProviderEnum`).
+ *
+ * 🔴 **Solo `FACEMATCH` está implementado.** Los demás están declarados a propósito: el contrato
+ * nace genérico para que agregar un biométrico no obligue a romperlo. Pedir uno no implementado
+ * devuelve `BIOMETRIC_NOT_SUPPORTED` (422) — un error explícito y accionable, nunca un 500.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export enum BiometricTypeEnum {
+    /** Comparar la selfie del momento contra una foto de referencia ya registrada. */
+    FACEMATCH = 'FACEMATCH',
+
+    /** ¿Hay una persona viva frente a la cámara? Declarado, sin implementar. */
+    LIVENESS = 'LIVENESS',
+
+    /** Verificación por voz. Declarado, sin implementar. */
+    VOICE = 'VOICE',
+
+    /** Comparar la cara contra la foto impresa en el documento. Declarado, sin implementar. */
+    DOCUMENT_MATCH = 'DOCUMENT_MATCH',
+}

package/src/biometrics/enums/BiometricVerificationStatusEnum.ts

@@ -0,0 +1,37 @@
+/**
+ * Dónde va el PROCESO de la verificación. **No dice cómo salió el biométrico** — eso es
+ * `BiometricResultEnum`.
+ *
+ * 🔴 **Están separados a propósito.** Aplastar los dos en un solo campo hace ambiguo un caso real y
+ * frecuente: el facematch ya dio `MATCH` (llegó el `step_completed`) pero la verificación todavía no
+ * cerró (falta el `verification_completed`). Con un campo único no hay forma de decir eso sin
+ * mentir en alguna dirección.
+ *
+ * **Los terminales no retroceden.** `COMPLETED`, `EXPIRED` y `FAILED` no vuelven a `IN_PROGRESS`
+ * aunque llegue un evento posterior — SQS no garantiza orden y la cola es at-least-once.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export enum BiometricVerificationStatusEnum {
+    /** Se emitió la entrega (link/challenge) y nadie la ha ejecutado todavía. */
+    PENDING = 'PENDING',
+
+    /** El usuario arrancó. Puede haber resultados parciales de estaciones. */
+    IN_PROGRESS = 'IN_PROGRESS',
+
+    /** El proveedor cerró la verificación. `result` tiene el veredicto final. */
+    COMPLETED = 'COMPLETED',
+
+    /**
+     * Venció sin completarse. Lo escribe el proveedor (`verification_expired`) **o** el propio `GET`
+     * al detectar `now > expiresAt` — y en ese caso lo PERSISTE (DEC-015). Si se calculara sin
+     * persistir, un cierre tardío escribiría `COMPLETED` sobre algo que el caller ya vio `EXPIRED`.
+     */
+    EXPIRED = 'EXPIRED',
+
+    /**
+     * Falla interna procesando la verificación. **El proveedor NO lo produce**: el catálogo de
+     * eventos de Metamap no tiene ninguno de error (DEC-013). `failureReason` es nuestro.
+     */
+    FAILED = 'FAILED',
+}

package/src/biometrics/events/BiometricVerificationChangedV1.ts

@@ -0,0 +1,114 @@
+import { Expose } from 'class-transformer';
+import {
+    IsEnum,
+    IsISO8601,
+    IsIn,
+    IsNotEmpty,
+    IsNumber,
+    IsOptional,
+    IsString,
+    Matches,
+    Max,
+    Min,
+} from 'class-validator';
+import { BiometricEventTypeEnum } from '../enums/BiometricEventTypeEnum';
+import { BiometricProviderEnum } from '../enums/BiometricProviderEnum';
+import { BiometricResultEnum } from '../enums/BiometricResultEnum';
+
+/**
+ * Lo que le pasó a una verificación biométrica, según el proveedor.
+ *
+ * **El recorrido:** Metamap → `kyc-metamap-webhook` (que valida la firma HMAC y traduce) →
+ * `BiometricsInboundQueue` → el consumer de `biometrics-business`, que aplica la transición.
+ *
+ * **Por qué el webhook no llama directo:** ese lambda tiene una disciplina explícita — *un fallo de
+ * publish NUNCA puede tumbar el webhook*, porque si lanza, Metamap reintenta el webhook completo y
+ * se duplican las actualizaciones de identidad. Con esa regla, una llamada síncrona que falle se
+ * traga el evento en silencio y la verificación queda `IN_PROGRESS` para siempre, con el caller
+ * poleando al vacío y sin alarma. La cola da durabilidad, DLQ y alarma sin tocar esa disciplina.
+ *
+ * 🔴 **Cola propia, NO `RetailKycInboundQueue`.** SQS no hace broadcast: dos lambdas sobre la misma
+ * cola son consumidores en competencia y cada mensaje le llega a UNO solo. Reusar la de SureKeep
+ * partiría sus KYC a la mitad, en producción, al azar y sin un solo error en los logs.
+ *
+ * 🔴 **Sin PII.** Solo identificadores operacionales y el veredicto.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export class BiometricVerificationChangedV1 {
+    /**
+     * Discriminador del tipo de mensaje. Fijo, para que el consumer rutee por él y no por adivinar
+     * la forma del payload.
+     */
+    @Expose() @IsOptional() @IsIn(['BiometricVerificationChangedV1'])
+    schema?: string;
+
+    /**
+     * 🔴 **Identificador ÚNICO de este evento. La clave de deduplicación.**
+     *
+     * SQS es *at-least-once*: los duplicados son la norma, no la excepción. Y **el candado temporal
+     * por `occurredAt` NO alcanza para esto**: dos entregas del mismo evento traen exactamente el
+     * mismo `occurredAt`, así que una regla "descartar si es más viejo" las deja pasar a las dos.
+     *
+     * El consumer guarda los `eventId` ya aplicados y descarta los repetidos.
+     *
+     * ⚠️ **No deduplicar por el `MessageId` de SQS**: cambia en cada reintento de entrega, así que
+     * no deduplica nada. Es el error clásico y por eso queda escrito acá y no en la cabeza de cada
+     * consumidor.
+     */
+    @Expose() @IsString() @IsNotEmpty()
+    eventId!: string;
+
+    /**
+     * A qué verificación se refiere. Sale del `metadata` que el proveedor ecoa tal cual → el
+     * consumer hace un `get` por PK, sin búsqueda.
+     */
+    @Expose() @IsString() @IsNotEmpty()
+    biometricVerificationId!: string;
+
+    /** Quién ejecutó el biométrico. */
+    @Expose() @IsEnum(BiometricProviderEnum)
+    provider!: BiometricProviderEnum;
+
+    /** El id del lado del proveedor (el `verificationId` de Metamap). Para soporte y reconciliación. */
+    @Expose() @IsOptional() @IsString() @IsNotEmpty()
+    providerRef?: string;
+
+    /** Qué pasó. Es lo que decide la transición de estado. */
+    @Expose() @IsEnum(BiometricEventTypeEnum)
+    eventType!: BiometricEventTypeEnum;
+
+    /**
+     * El veredicto, cuando el evento lo trae. Llega en el `STEP_COMPLETED`, **antes** del cierre —
+     * por eso el consumer puede poblar `result` con `status` todavía en `IN_PROGRESS`.
+     *
+     * Ausente en `VERIFICATION_STARTED` y `VERIFICATION_EXPIRED`.
+     */
+    @Expose() @IsOptional() @IsEnum(BiometricResultEnum)
+    result?: BiometricResultEnum;
+
+    /** Similitud reportada, 0–100, cuando el proveedor la expone. */
+    @Expose() @IsOptional() @IsNumber() @Min(0) @Max(100)
+    score?: number;
+
+    /**
+     * Cuándo ocurrió, según el proveedor. Obligatorio: es el candado de orden.
+     *
+     * ⚠️ **UTC estricto, con `Z` y sin offset** — por eso el `@Matches` además del `@IsISO8601()`.
+     * `@IsISO8601()` solo acepta `2026-07-26` (sin hora), `2026-W30-1` y, lo que hace daño de
+     * verdad, `2026-07-26T15:05:00+05:00`.
+     *
+     * 🔴 **El candado del consumer es LÉXICO.** Ese `+05:00` son las 10:05 UTC, pero comparado como
+     * texto es MAYOR que un `T10:06:00Z` posterior: el consumer lo leería como más nuevo, descartaría
+     * el evento real, y la transición no se aplicaría nunca — sin un solo error.
+     *
+     * Normalizar a UTC es trabajo del traductor del proveedor (`kyc-metamap-webhook`). Este candado
+     * existe para que si algún día deja de hacerlo, el mensaje caiga al DLQ en el boundary en vez de
+     * corromper el orden en silencio.
+     */
+    @Expose() @IsString() @IsISO8601({ strict: true })
+    @Matches(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/, {
+        message: 'occurredAt debe ser ISO-8601 en UTC con Z (ej. 2026-07-26T10:05:00.000Z): un offset rompe el orden lexico',
+    })
+    occurredAt!: string;
+}

package/src/biometrics/index.ts

@@ -0,0 +1,24 @@
+// Dominio `biometrics` — el contrato de `biometrics-business`, el master de la lógica biométrica
+// de Fiado. El caller dice QUÉ necesita y PARA QUIÉN; el proveedor (Metamap hoy; Apple, Google y
+// Amazon después) queda detrás de un port y no aparece en el contrato más que como un enum.
+
+// Enums
+export * from './enums/BiometricTypeEnum';
+export * from './enums/BiometricProviderEnum';
+export * from './enums/BiometricDeliveryModeEnum';
+export * from './enums/BiometricVerificationStatusEnum';
+export * from './enums/BiometricResultEnum';
+export * from './enums/BiometricEventTypeEnum';
+
+// DTOs compartidos
+export * from './dtos/BiometricSubject';
+export * from './dtos/BiometricDelivery';
+
+// Request DTOs
+export * from './dtos/requests/CreateBiometricVerificationRequest';
+
+// Response DTOs
+export * from './dtos/responses/BiometricVerificationResponse';
+
+// Events (BiometricsInboundQueue)
+export * from './events/BiometricVerificationChangedV1';

package/src/helpdesk/dtos/HelpdeskCreateTicketRequest.ts

@@ -1,4 +1,4 @@
-import { IsNotEmpty, IsString } from "class-validator";
+import { IsArray, IsBoolean, IsNotEmpty, IsNumber, IsOptional, IsString } from "class-validator";
 
 export class HelpdeskCreateTicketRequest {
 
@@ -27,4 +27,20 @@ export class HelpdeskCreateTicketRequest {
     @IsString()
     peopleId: string;
 
+    /** true → la nota se crea como comentario interno (solo agentes). Default: false. */
+    @IsBoolean()
+    @IsOptional()
+    internal?: boolean;
+
+    /** Tags del ticket (p. ej. ["kyc-listas", "interno"]) para vistas y triggers. */
+    @IsArray()
+    @IsString({ each: true })
+    @IsOptional()
+    tags?: string[];
+
+    /** GID del grupo de Zendesk al que se asigna (p. ej. Legal). */
+    @IsNumber()
+    @IsOptional()
+    groupId?: number;
+
 }

package/src/index.ts

@@ -1,6 +1,7 @@
 export * as Crypto from './crypto';
 export * as Account from './account';
 export * as MetamapConnector from './metamapConnector';
+export * as Biometrics from './biometrics';
 export * as Activity from './activity';
 export * as Beneficiary from './beneficiary';
 export * as Address from './address';