@fiado/type-kit 3.251.0 → 3.253.0

package/bin/biometrics/events/BiometricVerificationChangedV1.d.ts

@@ -0,0 +1,80 @@
+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 declare class BiometricVerificationChangedV1 {
+    /**
+     * Discriminador del tipo de mensaje. Fijo, para que el consumer rutee por él y no por adivinar
+     * la forma del payload.
+     */
+    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.
+     */
+    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.
+     */
+    biometricVerificationId: string;
+    /** Quién ejecutó el biométrico. */
+    provider: BiometricProviderEnum;
+    /** El id del lado del proveedor (el `verificationId` de Metamap). Para soporte y reconciliación. */
+    providerRef?: string;
+    /** Qué pasó. Es lo que decide la transición de estado. */
+    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`.
+     */
+    result?: BiometricResultEnum;
+    /** Similitud reportada, 0–100, cuando el proveedor la expone. */
+    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.
+     */
+    occurredAt: string;
+}

package/bin/biometrics/events/BiometricVerificationChangedV1.js

@@ -0,0 +1,98 @@
+"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.BiometricVerificationChangedV1 = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const BiometricEventTypeEnum_1 = require("../enums/BiometricEventTypeEnum");
+const BiometricProviderEnum_1 = require("../enums/BiometricProviderEnum");
+const BiometricResultEnum_1 = require("../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.
+ */
+class BiometricVerificationChangedV1 {
+}
+exports.BiometricVerificationChangedV1 = BiometricVerificationChangedV1;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsIn)(['BiometricVerificationChangedV1']),
+    __metadata("design:type", String)
+], BiometricVerificationChangedV1.prototype, "schema", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], BiometricVerificationChangedV1.prototype, "eventId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], BiometricVerificationChangedV1.prototype, "biometricVerificationId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(BiometricProviderEnum_1.BiometricProviderEnum),
+    __metadata("design:type", String)
+], BiometricVerificationChangedV1.prototype, "provider", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], BiometricVerificationChangedV1.prototype, "providerRef", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(BiometricEventTypeEnum_1.BiometricEventTypeEnum),
+    __metadata("design:type", String)
+], BiometricVerificationChangedV1.prototype, "eventType", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(BiometricResultEnum_1.BiometricResultEnum),
+    __metadata("design:type", String)
+], BiometricVerificationChangedV1.prototype, "result", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsNumber)(),
+    (0, class_validator_1.Min)(0),
+    (0, class_validator_1.Max)(100),
+    __metadata("design:type", Number)
+], BiometricVerificationChangedV1.prototype, "score", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsISO8601)({ strict: true }),
+    (0, class_validator_1.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',
+    }),
+    __metadata("design:type", String)
+], BiometricVerificationChangedV1.prototype, "occurredAt", void 0);

package/bin/biometrics/index.d.ts

@@ -0,0 +1,11 @@
+export * from './enums/BiometricTypeEnum';
+export * from './enums/BiometricProviderEnum';
+export * from './enums/BiometricDeliveryModeEnum';
+export * from './enums/BiometricVerificationStatusEnum';
+export * from './enums/BiometricResultEnum';
+export * from './enums/BiometricEventTypeEnum';
+export * from './dtos/BiometricSubject';
+export * from './dtos/BiometricDelivery';
+export * from './dtos/requests/CreateBiometricVerificationRequest';
+export * from './dtos/responses/BiometricVerificationResponse';
+export * from './events/BiometricVerificationChangedV1';

package/bin/biometrics/index.js

@@ -0,0 +1,35 @@
+"use strict";
+// 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.
+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 });
+// Enums
+__exportStar(require("./enums/BiometricTypeEnum"), exports);
+__exportStar(require("./enums/BiometricProviderEnum"), exports);
+__exportStar(require("./enums/BiometricDeliveryModeEnum"), exports);
+__exportStar(require("./enums/BiometricVerificationStatusEnum"), exports);
+__exportStar(require("./enums/BiometricResultEnum"), exports);
+__exportStar(require("./enums/BiometricEventTypeEnum"), exports);
+// DTOs compartidos
+__exportStar(require("./dtos/BiometricSubject"), exports);
+__exportStar(require("./dtos/BiometricDelivery"), exports);
+// Request DTOs
+__exportStar(require("./dtos/requests/CreateBiometricVerificationRequest"), exports);
+// Response DTOs
+__exportStar(require("./dtos/responses/BiometricVerificationResponse"), exports);
+// Events (BiometricsInboundQueue)
+__exportStar(require("./events/BiometricVerificationChangedV1"), exports);

package/bin/index.d.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';

package/bin/index.js

@@ -36,12 +36,13 @@ 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 });
-exports.Observations = exports.IssuanceBusiness = exports.Blacklist = exports.CentralPayments = exports.Helpdesk = exports.FiadoApiResponse = exports.Auth = exports.LegalDocumentsBusiness = exports.Role = exports.STPAccount = exports.RiskProfile = exports.FraudPreventionEngine = exports.BBVARst = exports.Stp = exports.BenefitCenter = exports.BankAccount = exports.P2pContact = exports.CreditContract = exports.Contract = exports.ProductCatalog = exports.ContactInfo = exports.TransactionAnalytics = exports.Transaction = exports.TransactionProcessor = exports.GenericMessage = exports.EventBridgeMessage = exports.SessionActivity = exports.NotificationMessages = exports.ServicePayment = exports.Header = exports.Identity = exports.UserTags = exports.Group = exports.File = exports.ExchangeRate = exports.Directory = exports.Currency = exports.Country = exports.Card = exports.Authentication = exports.AppContent = exports.App = exports.Offices = exports.Places = exports.Address = exports.Beneficiary = exports.Activity = exports.MetamapConnector = exports.Account = exports.Crypto = void 0;
-exports.LoanCollectorAssignment = exports.LoanOfferings = exports.Shortlink = exports.LoanConfig = exports.RetailWizard = exports.RetailCustomer = exports.RetailCards = exports.RetailCatalog = exports.RetailOrg = exports.EmailVerification = exports.NetworkConnector = exports.Modelias = exports.TotpSecurity = exports.Passport = exports.WalletFunding = exports.Remittance = exports.PlatformRbac = exports.CognitoBackofficeConnector = exports.TwilioConnector = exports.MessagesConnector = exports.Mdm = exports.MilestoneBusiness = exports.CirculoCredito = exports.CreditStatements = exports.Sentry = exports.AiEngine = exports.Funnel = exports.TeamsConnector = exports.PlatformErrorEvents = exports.CustomerFile = exports.CreditBackoffice = exports.CreditDashboard = exports.CreditEngine = exports.Credit = exports.ComissionBusiness = exports.ReferralBusiness = exports.ZendeskMessaging = exports.NotificationWS = exports.Event = exports.PayrollBusiness = exports.Cnbv = exports.DirectorySetting = exports.InvoiceCollector = exports.Collector = exports.Pricelist = exports.Company = exports.Services = exports.AccountIssuanceBusiness = exports.AppSelectionData = exports.Device = void 0;
-exports.Shipping = exports.PhoneSales = exports.Onboarding = exports.Kyc = exports.LoanScoring = exports.LoanCredit = void 0;
+exports.IssuanceBusiness = exports.Blacklist = exports.CentralPayments = exports.Helpdesk = exports.FiadoApiResponse = exports.Auth = exports.LegalDocumentsBusiness = exports.Role = exports.STPAccount = exports.RiskProfile = exports.FraudPreventionEngine = exports.BBVARst = exports.Stp = exports.BenefitCenter = exports.BankAccount = exports.P2pContact = exports.CreditContract = exports.Contract = exports.ProductCatalog = exports.ContactInfo = exports.TransactionAnalytics = exports.Transaction = exports.TransactionProcessor = exports.GenericMessage = exports.EventBridgeMessage = exports.SessionActivity = exports.NotificationMessages = exports.ServicePayment = exports.Header = exports.Identity = exports.UserTags = exports.Group = exports.File = exports.ExchangeRate = exports.Directory = exports.Currency = exports.Country = exports.Card = exports.Authentication = exports.AppContent = exports.App = exports.Offices = exports.Places = exports.Address = exports.Beneficiary = exports.Activity = exports.Biometrics = exports.MetamapConnector = exports.Account = exports.Crypto = void 0;
+exports.LoanOfferings = exports.Shortlink = exports.LoanConfig = exports.RetailWizard = exports.RetailCustomer = exports.RetailCards = exports.RetailCatalog = exports.RetailOrg = exports.EmailVerification = exports.NetworkConnector = exports.Modelias = exports.TotpSecurity = exports.Passport = exports.WalletFunding = exports.Remittance = exports.PlatformRbac = exports.CognitoBackofficeConnector = exports.TwilioConnector = exports.MessagesConnector = exports.Mdm = exports.MilestoneBusiness = exports.CirculoCredito = exports.CreditStatements = exports.Sentry = exports.AiEngine = exports.Funnel = exports.TeamsConnector = exports.PlatformErrorEvents = exports.CustomerFile = exports.CreditBackoffice = exports.CreditDashboard = exports.CreditEngine = exports.Credit = exports.ComissionBusiness = exports.ReferralBusiness = exports.ZendeskMessaging = exports.NotificationWS = exports.Event = exports.PayrollBusiness = exports.Cnbv = exports.DirectorySetting = exports.InvoiceCollector = exports.Collector = exports.Pricelist = exports.Company = exports.Services = exports.AccountIssuanceBusiness = exports.AppSelectionData = exports.Device = exports.Observations = void 0;
+exports.Shipping = exports.PhoneSales = exports.Onboarding = exports.Kyc = exports.LoanScoring = exports.LoanCredit = exports.LoanCollectorAssignment = void 0;
 exports.Crypto = __importStar(require("./crypto"));
 exports.Account = __importStar(require("./account"));
 exports.MetamapConnector = __importStar(require("./metamapConnector"));
+exports.Biometrics = __importStar(require("./biometrics"));
 exports.Activity = __importStar(require("./activity"));
 exports.Beneficiary = __importStar(require("./beneficiary"));
 exports.Address = __importStar(require("./address"));

package/bin/zendeskMessaging/dtos/SendProactiveMessageRequest.d.ts

@@ -2,4 +2,6 @@ export declare class SendProactiveMessageRequest {
     directoryId: string;
     message: string;
     displayName?: string;
+    /** Detalle técnico para el agente: se agrega (append) a las Notas del usuario en Zendesk. */
+    agentNote?: string;
 }

package/bin/zendeskMessaging/dtos/SendProactiveMessageRequest.js

@@ -29,3 +29,8 @@ __decorate([
     (0, class_validator_1.IsOptional)(),
     __metadata("design:type", String)
 ], SendProactiveMessageRequest.prototype, "displayName", void 0);
+__decorate([
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsOptional)(),
+    __metadata("design:type", String)
+], SendProactiveMessageRequest.prototype, "agentNote", void 0);

package/package.json

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

package/src/biometrics/dtos/BiometricDelivery.ts

@@ -0,0 +1,81 @@
+import { Expose } from 'class-transformer';
+import { IsISO8601, IsNotEmpty, IsOptional, IsString } from 'class-validator';
+
+/**
+ * Lo que el caller necesita para que el biométrico se ejecute. **Su forma la determina
+ * `BiometricVerificationResponse.deliveryMode`, que es el discriminador.**
+ *
+ * Se modela como TRES clases + una unión de tipos en vez de un objeto con todo opcional. Con la
+ * unión, TypeScript obliga al caller a hacer el `switch (deliveryMode)` y sabe exactamente qué
+ * campos tiene en cada rama. Con un objeto plano de campos opcionales, el compilador no ayuda y el
+ * caller termina haciendo `link!` — que es el bug esperando a que entre el segundo proveedor.
+ *
+ * `biometrics-business` — Entrega 1 (solo `RedirectDelivery` produce valores reales).
+ */
+
+/**
+ * `deliveryMode = REDIRECT`. El usuario abre el link y ejecuta el biométrico ahí.
+ * Es lo que produce Metamap: una URL hospedada, acortada, con TTL.
+ */
+export class RedirectDelivery {
+    /**
+     * La URL a abrir. Ya viene acortada — si el acortador no respondió, viene la larga.
+     * Que el acortador falle NO detiene la operación: un QR más denso se escanea igual.
+     */
+    @Expose() @IsString() @IsNotEmpty()
+    link!: string;
+
+    /** Hasta cuándo sirve el link. ISO-8601 UTC con `Z`. */
+    @Expose() @IsISO8601({ strict: true })
+    expiresAt!: string;
+}
+
+/**
+ * `deliveryMode = CHALLENGE`. El biométrico corre en el dispositivo (Apple Face ID, biometría de
+ * Android) y el cliente devuelve una attestation firmada.
+ *
+ * ⚠️ **Declarado, sin implementar.** El endpoint que recibe la attestation
+ * (`POST /.../{id}/assertion`) queda fuera de la Entrega 1 a propósito — el contrato ya lo admite
+ * sin romperse, que es todo lo que hacía falta decidir ahora.
+ */
+export class ChallengeDelivery {
+    /** El desafío que el dispositivo debe firmar. */
+    @Expose() @IsString() @IsNotEmpty()
+    challenge!: string;
+
+    /** Nonce anti-replay. Un solo uso. */
+    @Expose() @IsString() @IsNotEmpty()
+    nonce!: string;
+
+    /** Hasta cuándo sirve el challenge. ISO-8601 UTC con `Z`. */
+    @Expose() @IsISO8601({ strict: true })
+    expiresAt!: string;
+}
+
+/**
+ * `deliveryMode = IMMEDIATE`. No hay nada que entregar: el biométrico ya corrió en el servidor
+ * (Amazon Rekognition) y el veredicto viene en `result` de la misma respuesta.
+ *
+ * Vacío a propósito. Existe para que la unión sea exhaustiva y el `switch` del caller no necesite
+ * un `default` que trague casos nuevos en silencio.
+ *
+ * ⚠️ Declarado, sin implementar.
+ */
+export class ImmediateDelivery {
+    /** Reservado. Nunca se llena hoy — existe para que la clase no sea estructuralmente vacía. */
+    @Expose() @IsOptional() @IsString()
+    note?: string;
+}
+
+/**
+ * La unión. El caller discrimina con `deliveryMode`:
+ *
+ * ```ts
+ * switch (res.deliveryMode) {
+ *   case BiometricDeliveryModeEnum.REDIRECT:  abrir((res.delivery as RedirectDelivery).link); break;
+ *   case BiometricDeliveryModeEnum.CHALLENGE: firmar(res.delivery as ChallengeDelivery); break;
+ *   case BiometricDeliveryModeEnum.IMMEDIATE: leer(res.result); break;
+ * }
+ * ```
+ */
+export type BiometricDelivery = RedirectDelivery | ChallengeDelivery | ImmediateDelivery;

package/src/biometrics/dtos/BiometricSubject.ts

@@ -0,0 +1,54 @@
+import { Expose } from 'class-transformer';
+import { IsNotEmpty, IsOptional, IsString, Matches } from 'class-validator';
+
+/**
+ * Datos del SUJETO que el proveedor necesita, además del `directoryId`.
+ *
+ * 🔴 **Tipado y CERRADO, jamás un `Record<string, unknown>`.** Un mapa abierto en un boundary es
+ * antipatrón Fiado, pero el problema real es peor: sería un canal por el que cualquier caller le
+ * puede filtrar PII a un tercero sin que nadie lo revise. Lo que viaja a un proveedor externo se
+ * declara campo por campo.
+ *
+ * **No confundir con `callerContext`**, que es correlación opaca del caller y NUNCA sale de Fiado.
+ * Son dos cosas que se mezclan seguido: "datos que el proveedor necesita" vs "mi correlación".
+ *
+ * **Todos opcionales, con resolución del lado del servicio (DEC-005b).** Lo que venga acá gana; lo
+ * que falte, `biometrics-business` lo resuelve contra `fiado-identity-lambda` a partir del
+ * `directoryId`. Si tras eso sigue faltando alguno, responde `SUBJECT_DATA_INCOMPLETE` (422)
+ * nombrando los CAMPOS, jamás sus valores.
+ *
+ * 🔴 **Ese error existe para prevenir una falla muda ya vivida.** Con la metadata de identidad
+ * vacía, el proveedor genera una verificación HUÉRFANA: el usuario hace la selfie completa, el
+ * webhook no la puede asociar a nadie, y el flujo queda colgado para siempre con la persona ya
+ * fuera de la tienda. Fallar temprano y ruidoso es la única respuesta correcta.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export class BiometricSubject {
+    /** Identificador de la persona en el directorio de Fiado. */
+    @Expose() @IsOptional() @IsString() @IsNotEmpty()
+    peopleId?: string;
+
+    /**
+     * País del sujeto en el catálogo de Fiado (`CountryId`). MX es `'484'`.
+     *
+     * ⚠️ Numérico-como-string a propósito: es el mismo valor que usa el resto de la plataforma.
+     * Un caller que mande `'MX'` acá rompería la metadata del proveedor.
+     */
+    @Expose() @IsOptional() @IsString() @IsNotEmpty()
+    countryId?: string;
+
+    /**
+     * Teléfono **ya en E.164**, con `+` y código de país (`+521234567890`).
+     *
+     * ⚠️ **La normalización es del caller, no de este servicio.** El wizard, por ejemplo, guarda 10
+     * dígitos crudos en su sesión y los convierte con `toE164Mx()` solo al cruzar hacia el
+     * proveedor. Mandar 10 dígitos pelados acá produce una metadata que el proveedor acepta y que
+     * después nadie puede reconciliar.
+     */
+    @Expose() @IsOptional() @IsString()
+    @Matches(/^\+[1-9]\d{7,14}$/, {
+        message: 'phoneNumber debe venir en E.164 con + y codigo de pais (ej. +521234567890)',
+    })
+    phoneNumber?: string;
+}

package/src/biometrics/dtos/requests/CreateBiometricVerificationRequest.ts

@@ -0,0 +1,101 @@
+import { Expose, Type } from 'class-transformer';
+import {
+    IsEnum,
+    IsInt,
+    IsNotEmpty,
+    IsOptional,
+    IsString,
+    Max,
+    MaxLength,
+    Min,
+    ValidateNested,
+} from 'class-validator';
+import { BiometricProviderEnum } from '../../enums/BiometricProviderEnum';
+import { BiometricTypeEnum } from '../../enums/BiometricTypeEnum';
+import { BiometricSubject } from '../BiometricSubject';
+
+/**
+ * `POST /private/biometric-verifications` — pedir una verificación biométrica de una persona.
+ *
+ * El caller dice QUÉ necesita (`type`), QUIÉN lo ejecuta (`provider`) y PARA QUIÉN es
+ * (`directoryId`). Todo lo demás — resolver la foto de referencia, publicarla, firmarla, armar la
+ * metadata del proveedor, acortar el link — lo hace `biometrics-business`. Ese es el punto: que el
+ * segundo producto que necesite biometría haga un `POST` en vez de un proyecto.
+ *
+ * `biometrics-business` — Entrega 1.
+ */
+export class CreateBiometricVerificationRequest {
+    /**
+     * QUÉ biométrico. Hoy solo `FACEMATCH` está implementado; el resto devuelve
+     * `BIOMETRIC_NOT_SUPPORTED` (422).
+     */
+    @Expose() @IsEnum(BiometricTypeEnum)
+    type!: BiometricTypeEnum;
+
+    /**
+     * QUIÉN lo ejecuta. **Obligatorio** (DEC-004): el caller lo nombra, el servicio no resuelve un
+     * default. Hoy solo `METAMAP`.
+     *
+     * ⚠️ **TD-001**: esto acopla a los callers. Cambiar de proveedor obliga a tocar y redesplegar a
+     * todos. Se aceptó a cambio de que la elección sea explícita y auditable en cada request.
+     */
+    @Expose() @IsEnum(BiometricProviderEnum)
+    provider!: BiometricProviderEnum;
+
+    /**
+     * PARA QUIÉN es. Es la llave con la que se resuelve la foto de referencia y los datos que falten
+     * de `subject`.
+     *
+     * `@IsNotEmpty()` y no solo `@IsString()`: un `''` colado pasaría el boundary y fallaría tres
+     * pasos río abajo, contra identity, con un error que no apunta a nada.
+     */
+    @Expose() @IsString() @IsNotEmpty()
+    directoryId!: string;
+
+    /**
+     * QUIÉN pide (el producto o lambda: `surekeep-wizard`, `user-wallet-app`…). Para auditoría y
+     * trazabilidad.
+     *
+     * ⚠️ **No autoriza nada** (TD-009). El `GET` no lo valida: hoy el aislamiento es que los dos
+     * endpoints son VPC-only, así que solo lambdas de Fiado llegan. Está anotado como deuda
+     * consciente, no como olvido.
+     */
+    @Expose() @IsString() @IsNotEmpty()
+    requestedBy!: string;
+
+    /**
+     * Datos del sujeto que el proveedor necesita. Lo que mandes gana; lo que falte se resuelve
+     * contra identity. Ver `BiometricSubject` — sobre todo la nota de por qué `phoneNumber` va en
+     * E.164 y la normalización es tuya.
+     */
+    @Expose() @IsOptional() @ValidateNested() @Type(() => BiometricSubject)
+    subject?: BiometricSubject;
+
+    /**
+     * Override de la foto de referencia. Si no viene, el servicio la resuelve solo: pide la **selfie
+     * del KYC** a identity (no el avatar `PROFILE_PICTURE`, que el KYC nunca genera) y la publica.
+     *
+     * Úsalo solo si ya tienes la foto correcta a mano y quieres ahorrarte el round-trip.
+     */
+    @Expose() @IsOptional() @IsString() @IsNotEmpty()
+    referenceImageUrl?: string;
+
+    /**
+     * Vigencia de la entrega, en segundos. Default 3600.
+     *
+     * El techo de 24 h no es arbitrario: lo que se entrega es una identidad abierta. Un link de
+     * verificación que sobreviva a la operación que lo pidió es una puerta sin nadie mirándola.
+     */
+    @Expose() @IsOptional() @IsInt() @Min(60) @Max(86400)
+    ttlSeconds?: number;
+
+    /**
+     * Correlación tuya, opaca. Te la devuelvo intacta en el `GET`.
+     *
+     * 🔴 **NUNCA viaja al proveedor.** Es lo que la separa de `subject`: uno son datos que el
+     * tercero necesita, esto es un dato que solo te sirve a ti. No metas PII acá — mete tu id de
+     * sesión, de orden, de lo que sea que estés correlacionando.
+     */
+    @Expose() @IsOptional() @IsString() @MaxLength(256)
+    callerContext?: string;
+}

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;
+}