@fiado/type-kit 3.609.0 → 3.610.0

package/_test_/unit/biometrics/BiometricEventTypeEnum.test.ts

@@ -0,0 +1,35 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { BiometricEventTypeEnum, BiometricVerificationChangedV1 } from '../../../src/biometrics/index';
+
+const base = {
+  eventId: 'evt-1',
+  biometricVerificationId: 'bio-1',
+  provider: 'METAMAP',
+  eventType: 'VERIFICATION_STARTED',
+  occurredAt: '2026-10-28T10:05:00.000Z',
+};
+
+describe('BiometricEventTypeEnum', () => {
+  it('declara los seis eventos que traduce el webhook', () => {
+    expect(Object.values(BiometricEventTypeEnum)).toEqual([
+      'VERIFICATION_STARTED',
+      'STEP_COMPLETED',
+      'VERIFICATION_COMPLETED',
+      'VERIFICATION_EXPIRED',
+      'INPUTS_COMPLETED',
+      'UPDATED',
+    ]);
+  });
+
+  it.each([BiometricEventTypeEnum.INPUTS_COMPLETED, BiometricEventTypeEnum.UPDATED])(
+    'BiometricVerificationChangedV1 acepta el eventType %s',
+    async (eventType) => {
+      const dto = plainToInstance(BiometricVerificationChangedV1, { ...base, eventType }, { excludeExtraneousValues: true });
+
+      expect(await validate(dto as object)).toHaveLength(0);
+      expect(dto.eventType).toBe(eventType);
+    },
+  );
+});

package/_test_/unit/biometrics/BiometricVerificationResponse.test.ts

@@ -60,4 +60,23 @@ describe('BiometricVerificationResponse', () => {
       expect(instancia(base).referenceImageSource).toBe(BiometricReferenceSourceEnum.KYC_SELFIE);
     });
   });
+
+  // Cuándo el cliente terminó de subir su información; lo usa el wizard para INPUTS_COMPLETED.
+  describe('inputsCompletedAt', () => {
+    it('es opcional', async () => {
+      expect(await propiedadesConError(base)).toEqual([]);
+      expect(instancia(base).inputsCompletedAt).toBeUndefined();
+    });
+
+    it('acepta ISO-8601 UTC y sobrevive al plainToInstance', async () => {
+      const raw = { ...base, inputsCompletedAt: '2026-10-28T10:07:00.000Z' };
+
+      expect(await propiedadesConError(raw)).toEqual([]);
+      expect(instancia(raw).inputsCompletedAt).toBe('2026-10-28T10:07:00.000Z');
+    });
+
+    it('rechaza una fecha que no es ISO-8601', async () => {
+      expect(await propiedadesConError({ ...base, inputsCompletedAt: '28/10/2026' })).toContain('inputsCompletedAt');
+    });
+  });
 });

package/_test_/unit/kyc/KycProgressEnums.test.ts

@@ -0,0 +1,20 @@
+import 'reflect-metadata';
+import { KycFlowEnum, KycProgressStageEnum } from '../../../src/kyc/index';
+import { KycMetadataStepEnum } from '../../../src/retailWizard/index';
+
+describe('KycProgressStageEnum', () => {
+  it('declara solo las tres etapas que publica el webhook', () => {
+    expect(Object.values(KycProgressStageEnum)).toEqual(['STARTED', 'INPUTS_COMPLETED', 'EXPIRED']);
+  });
+});
+
+describe('KycFlowEnum', () => {
+  it('declara los dos flujos de Metamap que salen del wizard', () => {
+    expect(Object.values(KycFlowEnum)).toEqual(['IDENTITY', 'PROOF_OF_ADDRESS']);
+  });
+
+  // El webhook deriva flow de metadata.kycStep: si los valores divergen, el comprobante se rutea como identidad.
+  it('PROOF_OF_ADDRESS coincide con el kycStep de la metadata', () => {
+    expect(KycFlowEnum.PROOF_OF_ADDRESS).toBe(KycMetadataStepEnum.PROOF_OF_ADDRESS);
+  });
+});

package/_test_/unit/kyc/KycProofOfAddressCompletedV1.test.ts

@@ -192,4 +192,28 @@ describe('KycProofOfAddressCompletedV1', () => {
       ].sort(),
     );
   });
+
+  // ── Intento (estados MetaMap/QR) ──────────────────────────────────────────
+
+  describe('attemptId', () => {
+    it('acepta y expone attemptId', async () => {
+      const dto = instancia({ ...base, attemptId: 'att-1' });
+
+      expect(await validate(dto as object)).toHaveLength(0);
+      expect(dto.attemptId).toBe('att-1');
+    });
+
+    it('valida sin attemptId (compatibilidad hacia atrás)', async () => {
+      const dto = instancia(base);
+
+      expect(await validate(dto as object)).toHaveLength(0);
+      expect(dto.attemptId).toBeUndefined();
+    });
+
+    it('rechaza attemptId vacío', async () => {
+      const errors = await validate(instancia({ ...base, attemptId: '' }) as object);
+
+      expect(errors.map((e) => e.property)).toContain('attemptId');
+    });
+  });
 });

package/_test_/unit/kyc/KycStepCompletedV1.test.ts

@@ -2,6 +2,7 @@ import 'reflect-metadata';
 import { plainToInstance } from 'class-transformer';
 import { validate } from 'class-validator';
 import {
+  KycFlowEnum,
   KycStepCompletedV1,
   KycVerificationChangedV1,
   KycSubCheckNameEnum,
@@ -236,4 +237,37 @@ describe('KycStepCompletedV1', () => {
     );
     expect(Object.values(KycWatchlistStatusEnum)).toEqual(['CLEAR', 'HIT']);
   });
+
+  // ── Intento y flujo (estados MetaMap/QR) ──────────────────────────────────
+
+  describe('attemptId y flow', () => {
+    it('acepta y expone attemptId y flow', async () => {
+      const dto = instancia({ ...base, attemptId: 'att-1', flow: 'IDENTITY' });
+
+      expect(await validate(dto as object)).toHaveLength(0);
+      expect(dto.attemptId).toBe('att-1');
+      expect(dto.flow).toBe(KycFlowEnum.IDENTITY);
+    });
+
+    // Mensajes en vuelo y sesiones previas al despliegue no los traen.
+    it('valida sin attemptId ni flow', async () => {
+      const dto = instancia(base);
+
+      expect(await validate(dto as object)).toHaveLength(0);
+      expect(dto.attemptId).toBeUndefined();
+      expect(dto.flow).toBeUndefined();
+    });
+
+    it('rechaza attemptId vacío', async () => {
+      const errors = await validate(instancia({ ...base, attemptId: '' }) as object);
+
+      expect(errors.map((e) => e.property)).toContain('attemptId');
+    });
+
+    it.each(['FACEMATCH', 'identity'])('rechaza el flow %s', async (flow) => {
+      const errors = await validate(instancia({ ...base, flow }) as object);
+
+      expect(errors.map((e) => e.property)).toContain('flow');
+    });
+  });
 });

package/_test_/unit/kyc/KycVerificationChangedV1.test.ts

@@ -152,4 +152,34 @@ describe('KycVerificationChangedV1', () => {
 
     expect(errors.map((e) => e.property)).toContain('updateDate');
   });
+
+  // Estados MetaMap/QR: el cierre trae el intento para que el wizard descarte los ajenos.
+  describe('attemptId', () => {
+    const closing = {
+      verificationId: 'ver-1', directoryId: 'dir-1', peopleId: 'ppl-1',
+      verificationStatus: 'COMPLETED', verificationResult: 'VERIFIED',
+      updateDate: '2026-10-28T10:05:00.000Z',
+    };
+
+    it('acepta y expone attemptId', async () => {
+      const dto = plainToInstance(KycVerificationChangedV1, { ...closing, attemptId: 'att-1' }, { excludeExtraneousValues: true });
+
+      expect(await validate(dto as object)).toHaveLength(0);
+      expect(dto.attemptId).toBe('att-1');
+    });
+
+    it('valida sin attemptId (compatibilidad hacia atrás)', async () => {
+      const dto = plainToInstance(KycVerificationChangedV1, closing, { excludeExtraneousValues: true });
+
+      expect(await validate(dto as object)).toHaveLength(0);
+      expect(dto.attemptId).toBeUndefined();
+    });
+
+    it('rechaza attemptId vacío', async () => {
+      const dto = plainToInstance(KycVerificationChangedV1, { ...closing, attemptId: '' }, { excludeExtraneousValues: true });
+      const errors = await validate(dto as object);
+
+      expect(errors.map((e) => e.property)).toContain('attemptId');
+    });
+  });
 });

package/_test_/unit/kyc/KycVerificationProgressV1.test.ts

@@ -0,0 +1,144 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+  KycFlowEnum,
+  KycProgressStageEnum,
+  KycProofOfAddressCompletedV1,
+  KycStepCompletedV1,
+  KycVerificationChangedV1,
+  KycVerificationProgressV1,
+} from '../../../src/kyc/index';
+
+/** Base válida; cada caso pisa solo el campo que prueba. */
+const base = {
+  eventType: 'KycVerificationProgressV1',
+  stage: 'STARTED',
+  flow: 'IDENTITY',
+  verificationId: 'ver-1',
+  directoryId: 'dir-1',
+  attemptId: 'att-1',
+  occurredAt: '2026-10-28T10:05:00.000Z',
+};
+
+const toDto = (raw: Record<string, unknown>): KycVerificationProgressV1 =>
+  plainToInstance(KycVerificationProgressV1, raw, { excludeExtraneousValues: true });
+
+const errorProps = async (raw: Record<string, unknown>): Promise<string[]> =>
+  (await validate(toDto(raw) as object)).map((e) => e.property);
+
+describe('KycVerificationProgressV1', () => {
+  it('valida el shape que publica el webhook', async () => {
+    const dto = toDto(base);
+
+    expect(await errorProps(base)).toEqual([]);
+    expect(dto.stage).toBe(KycProgressStageEnum.STARTED);
+    expect(dto.flow).toBe(KycFlowEnum.IDENTITY);
+    expect(dto.attemptId).toBe('att-1');
+  });
+
+  it.each(Object.values(KycProgressStageEnum))('acepta la etapa %s', async (stage) => {
+    expect(await errorProps({ ...base, stage })).toEqual([]);
+  });
+
+  it.each(Object.values(KycFlowEnum))('acepta el flujo %s', async (flow) => {
+    expect(await errorProps({ ...base, flow })).toEqual([]);
+  });
+
+  // Sesiones creadas antes del despliegue: la metadata no trae attemptId.
+  it('valida sin attemptId', async () => {
+    const { attemptId: _omitted, ...withoutAttempt } = base;
+
+    expect(await errorProps(withoutAttempt)).toEqual([]);
+    expect(toDto(withoutAttempt).attemptId).toBeUndefined();
+  });
+
+  it('rechaza attemptId vacío', async () => {
+    expect(await errorProps({ ...base, attemptId: '' })).toContain('attemptId');
+  });
+
+  describe('eventType', () => {
+    it('rechaza el evento sin eventType', async () => {
+      const { eventType: _omitted, ...withoutType } = base;
+
+      expect(await errorProps(withoutType)).toContain('eventType');
+    });
+
+    it('rechaza el eventType de otro evento', async () => {
+      expect(await errorProps({ ...base, eventType: 'KycStepCompletedV1' })).toContain('eventType');
+    });
+  });
+
+  // AWAITING_START y RESULT son etapas del wizard, nunca llegan por evento.
+  it.each(['AWAITING_START', 'RESULT', 'COMPLETED'])('rechaza la etapa %s', async (stage) => {
+    expect(await errorProps({ ...base, stage })).toContain('stage');
+  });
+
+  // FACEMATCH no pasa por este evento: su avance sale del GET de biometrics.
+  it('rechaza el flujo FACEMATCH', async () => {
+    expect(await errorProps({ ...base, flow: 'FACEMATCH' })).toContain('flow');
+  });
+
+  it.each(['verificationId', 'directoryId'])('rechaza %s vacío', async (field) => {
+    expect(await errorProps({ ...base, [field]: '' })).toContain(field);
+  });
+
+  it.each(['stage', 'flow', 'verificationId', 'directoryId', 'occurredAt'])('rechaza el evento sin %s', async (field) => {
+    const raw: Record<string, unknown> = { ...base };
+    delete raw[field];
+
+    expect(await errorProps(raw)).toContain(field);
+  });
+
+  describe('occurredAt', () => {
+    it.each([
+      ['offset positivo en vez de Z', '2026-10-28T15:05:00+05:00'],
+      ['solo fecha, sin hora', '2026-10-28'],
+      ['sin zona horaria', '2026-10-28T10:05:00'],
+      ['formato local', '28/10/2026'],
+    ])('rechaza occurredAt %s', async (_label, value) => {
+      expect(await errorProps({ ...base, occurredAt: value })).toContain('occurredAt');
+    });
+
+    it.each([
+      ['con milisegundos', '2026-10-28T10:05:00.000Z'],
+      ['sin milisegundos', '2026-10-28T10:05:00Z'],
+    ])('acepta occurredAt en UTC %s', async (_label, value) => {
+      expect(await errorProps({ ...base, occurredAt: value })).toEqual([]);
+    });
+  });
+
+  // Comparte RetailKycInboundQueue con otros tres eventos: ninguno se puede hacer pasar por otro.
+  describe('convivencia en RetailKycInboundQueue', () => {
+    it('un avance NO valida como estación', async () => {
+      const errors = await validate(plainToInstance(KycStepCompletedV1, base, { excludeExtraneousValues: true }) as object);
+
+      expect(errors.map((e) => e.property)).toEqual(expect.arrayContaining(['eventType', 'step', 'status']));
+    });
+
+    it('un avance NO valida como cierre', async () => {
+      const errors = await validate(plainToInstance(KycVerificationChangedV1, base, { excludeExtraneousValues: true }) as object);
+
+      expect(errors.map((e) => e.property)).toEqual(
+        expect.arrayContaining(['peopleId', 'verificationStatus', 'verificationResult', 'updateDate']),
+      );
+    });
+
+    it('un avance NO valida como comprobante', async () => {
+      const errors = await validate(
+        plainToInstance(KycProofOfAddressCompletedV1, base, { excludeExtraneousValues: true }) as object,
+      );
+
+      expect(errors.map((e) => e.property)).toEqual(expect.arrayContaining(['eventType', 'status', 'addressPersisted']));
+    });
+
+    it('una estación NO valida como avance', async () => {
+      const station = {
+        eventType: 'KycStepCompletedV1', verificationId: 'ver-1', directoryId: 'dir-1',
+        step: 'facematch', status: 'PASS', occurredAt: '2026-10-28T10:05:00.000Z',
+      };
+
+      expect(await errorProps(station)).toEqual(expect.arrayContaining(['eventType', 'stage', 'flow']));
+    });
+  });
+});

package/_test_/unit/retailWizard/kycAttemptProgress.test.ts

@@ -0,0 +1,131 @@
+import 'reflect-metadata';
+import { KycProgressStageEnum } from '../../../src/kyc/index';
+import { KycModalityEnum } from '../../../src/retailCustomer/enums/KycModalityEnum';
+import {
+  KycAttemptStageEnum,
+  KycMetadataSourceEnum,
+  KycMetadataStepEnum,
+  type KycAttemptProgress,
+  type KycPrepareResponse,
+  type KycSdkMetadata,
+  type KycStatusProgress,
+  type ProofOfAddressPrepareResponse,
+} from '../../../src/retailWizard/index';
+
+const qrAttempt: KycAttemptProgress = {
+  attemptId: 'att-1',
+  modality: KycModalityEnum.CUSTOMER_LINK,
+  link: 'https://sk.fiado.test/abc',
+  stage: KycAttemptStageEnum.STARTED,
+  stageAt: '2026-10-28T10:05:00.000Z',
+  attemptStartedAt: '2026-10-28T10:00:00.000Z',
+};
+
+const tabletAttempt: KycAttemptProgress = {
+  attemptId: 'att-2',
+  modality: KycModalityEnum.STORE_DEVICE,
+  stage: KycAttemptStageEnum.AWAITING_START,
+  stageAt: '2026-10-28T10:00:00.000Z',
+  attemptStartedAt: '2026-10-28T10:00:00.000Z',
+};
+
+describe('KycAttemptStageEnum', () => {
+  it('declara las cinco etapas en orden de rango', () => {
+    expect(Object.values(KycAttemptStageEnum)).toEqual([
+      'AWAITING_START', 'STARTED', 'INPUTS_COMPLETED', 'EXPIRED', 'RESULT',
+    ]);
+  });
+
+  // El wizard copia la etapa del evento al intento por valor.
+  it.each(Object.values(KycProgressStageEnum))('incluye la etapa de evento %s', (stage) => {
+    expect(Object.values(KycAttemptStageEnum)).toContain(stage);
+  });
+});
+
+describe('KycAttemptProgress', () => {
+  it('lleva link en QR y lo omite en tablet', () => {
+    expect(qrAttempt.link).toBe('https://sk.fiado.test/abc');
+    expect(tabletAttempt.link).toBeUndefined();
+  });
+
+  it('solo admite las modalidades de prepare', () => {
+    const manual: KycAttemptProgress = {
+      ...tabletAttempt,
+      // @ts-expect-error MANUAL no es una modalidad de prepare
+      modality: KycModalityEnum.MANUAL,
+    };
+
+    expect(manual.modality).toBe('MANUAL');
+  });
+
+  // El tope de 25 min del front se mide contra la fecha del prepare, no contra el montaje.
+  it('exige attemptStartedAt', () => {
+    const { attemptStartedAt: _omitted, ...rest } = qrAttempt;
+    // @ts-expect-error attemptStartedAt es obligatorio
+    const withoutStart: KycAttemptProgress = rest;
+
+    expect(qrAttempt.attemptStartedAt).toBe('2026-10-28T10:00:00.000Z');
+    expect(withoutStart.attemptStartedAt).toBeUndefined();
+  });
+});
+
+describe('KycStatusProgress', () => {
+  it('trae un intento o null por cada flujo', () => {
+    const progress: KycStatusProgress = { identity: qrAttempt, facematch: null, proofOfAddress: tabletAttempt };
+
+    expect(Object.keys(progress).sort()).toEqual(['facematch', 'identity', 'proofOfAddress']);
+    expect(progress.facematch).toBeNull();
+  });
+});
+
+describe('KycSdkMetadata', () => {
+  it('acepta attemptId junto a source y kycStep', () => {
+    const metadata: KycSdkMetadata = {
+      directoryId: 'dir-1',
+      typeOfDirectoryId: 'PHONE',
+      peopleId: 'ppl-1',
+      countryId: 'MX',
+      phoneNumber: '5512345678',
+      source: KycMetadataSourceEnum.SUREKEEP_WIZARD,
+      kycStep: KycMetadataStepEnum.PROOF_OF_ADDRESS,
+      attemptId: 'att-1',
+    };
+
+    expect(metadata.attemptId).toBe('att-1');
+  });
+});
+
+// El front liga el SDK y los callbacks al attemptId que devuelve el prepare.
+describe('attemptId en las respuestas de prepare', () => {
+  // Sin intento creado (alreadyVerified o bypass de dev) no hay attemptId.
+  it('KycPrepareResponse lleva attemptId al preparar y lo omite sin intento', () => {
+    const prepared: KycPrepareResponse = {
+      modality: KycModalityEnum.CUSTOMER_LINK,
+      shortUrl: 'https://sk.fiado.test/abc',
+      attemptId: 'att-1',
+    };
+    const alreadyVerified: KycPrepareResponse = {
+      modality: KycModalityEnum.CUSTOMER_LINK,
+      alreadyVerified: true,
+    };
+
+    expect(prepared.attemptId).toBe('att-1');
+    expect(alreadyVerified.attemptId).toBeUndefined();
+  });
+
+  // Con domicilio ya registrado no se crea intento, por eso no hay attemptId.
+  it('ProofOfAddressPrepareResponse lleva attemptId al preparar y lo omite con alreadyHasAddress', () => {
+    const prepared: ProofOfAddressPrepareResponse = {
+      modality: KycModalityEnum.STORE_DEVICE,
+      clientId: 'client-1',
+      attemptId: 'att-3',
+    };
+    const alreadyHasAddress: ProofOfAddressPrepareResponse = {
+      modality: KycModalityEnum.STORE_DEVICE,
+      alreadyHasAddress: true,
+    };
+
+    expect(prepared.attemptId).toBe('att-3');
+    expect(alreadyHasAddress.attemptId).toBeUndefined();
+  });
+});

package/bin/biometrics/dtos/responses/BiometricVerificationResponse.d.ts

@@ -91,6 +91,8 @@ export declare class BiometricVerificationResponse {
     updatedAt: string;
     /** Cuándo vence la entrega. Es lo que el `GET` compara para persistir `EXPIRED` (DEC-015). */
     expiresAt: string;
+    /** Cuándo el usuario terminó de subir su información. ISO-8601 UTC con `Z`; ausente si aún no. */
+    inputsCompletedAt?: string;
     /** Cuándo alcanzó un estado terminal. Ausente mientras siga viva. */
     completedAt?: string;
 }

package/bin/biometrics/dtos/responses/BiometricVerificationResponse.js

@@ -129,6 +129,12 @@ __decorate([
     (0, class_validator_1.IsISO8601)({ strict: true }),
     __metadata("design:type", String)
 ], BiometricVerificationResponse.prototype, "expiresAt", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsISO8601)({ strict: true }),
+    __metadata("design:type", String)
+], BiometricVerificationResponse.prototype, "inputsCompletedAt", void 0);
 __decorate([
     (0, class_transformer_1.Expose)(),
     (0, class_validator_1.IsOptional)(),

package/bin/biometrics/enums/BiometricEventTypeEnum.d.ts

@@ -3,8 +3,8 @@
  * 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.
+ * estos valores 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 valores.
  *
  * `biometrics-business` — Entrega 1.
  */
@@ -24,5 +24,9 @@ export declare enum BiometricEventTypeEnum {
      * ⚠️ **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"
+    VERIFICATION_EXPIRED = "VERIFICATION_EXPIRED",
+    /** El usuario terminó de subir su información. Sigue en `IN_PROGRESS` y graba `inputsCompletedAt`. */
+    INPUTS_COMPLETED = "INPUTS_COMPLETED",
+    /** El proveedor cambió el veredicto (revisión manual). Se trata igual que `VERIFICATION_COMPLETED`. */
+    UPDATED = "UPDATED"
 }

package/bin/biometrics/enums/BiometricEventTypeEnum.js

@@ -6,8 +6,8 @@ exports.BiometricEventTypeEnum = void 0;
  * 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.
+ * estos valores 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 valores.
  *
  * `biometrics-business` — Entrega 1.
  */
@@ -29,4 +29,8 @@ var BiometricEventTypeEnum;
      * contra `expiresAt` (DEC-015), así que una verificación vence aunque este evento nunca llegue.
      */
     BiometricEventTypeEnum["VERIFICATION_EXPIRED"] = "VERIFICATION_EXPIRED";
+    /** El usuario terminó de subir su información. Sigue en `IN_PROGRESS` y graba `inputsCompletedAt`. */
+    BiometricEventTypeEnum["INPUTS_COMPLETED"] = "INPUTS_COMPLETED";
+    /** El proveedor cambió el veredicto (revisión manual). Se trata igual que `VERIFICATION_COMPLETED`. */
+    BiometricEventTypeEnum["UPDATED"] = "UPDATED";
 })(BiometricEventTypeEnum || (exports.BiometricEventTypeEnum = BiometricEventTypeEnum = {}));

package/bin/kyc/enums/KycFlowEnum.d.ts

@@ -0,0 +1,5 @@
+/** Flujo de Metamap al que pertenece un evento; el webhook lo deriva de `metadata.kycStep`. */
+export declare enum KycFlowEnum {
+    IDENTITY = "IDENTITY",
+    PROOF_OF_ADDRESS = "PROOF_OF_ADDRESS"
+}

package/bin/kyc/enums/KycFlowEnum.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KycFlowEnum = void 0;
+/** Flujo de Metamap al que pertenece un evento; el webhook lo deriva de `metadata.kycStep`. */
+var KycFlowEnum;
+(function (KycFlowEnum) {
+    KycFlowEnum["IDENTITY"] = "IDENTITY";
+    KycFlowEnum["PROOF_OF_ADDRESS"] = "PROOF_OF_ADDRESS";
+})(KycFlowEnum || (exports.KycFlowEnum = KycFlowEnum = {}));

package/bin/kyc/enums/KycProgressStageEnum.d.ts

@@ -0,0 +1,6 @@
+/** Etapa de avance de una verificación de Metamap, tal como la publica `kyc-metamap-webhook`. */
+export declare enum KycProgressStageEnum {
+    STARTED = "STARTED",
+    INPUTS_COMPLETED = "INPUTS_COMPLETED",
+    EXPIRED = "EXPIRED"
+}

package/bin/kyc/enums/KycProgressStageEnum.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KycProgressStageEnum = void 0;
+/** Etapa de avance de una verificación de Metamap, tal como la publica `kyc-metamap-webhook`. */
+var KycProgressStageEnum;
+(function (KycProgressStageEnum) {
+    KycProgressStageEnum["STARTED"] = "STARTED";
+    KycProgressStageEnum["INPUTS_COMPLETED"] = "INPUTS_COMPLETED";
+    KycProgressStageEnum["EXPIRED"] = "EXPIRED";
+})(KycProgressStageEnum || (exports.KycProgressStageEnum = KycProgressStageEnum = {}));

package/bin/kyc/events/KycProofOfAddressCompletedV1.d.ts

@@ -46,4 +46,6 @@ export declare class KycProofOfAddressCompletedV1 {
      * truena. Normalizar a UTC es trabajo del webhook; este candado lo manda al DLQ si deja de hacerlo.
      */
     occurredAt: string;
+    /** Intento del wizard que originó el comprobante; el consumidor descarta los que no son el vigente. */
+    attemptId?: string;
 }

package/bin/kyc/events/KycProofOfAddressCompletedV1.js

@@ -73,3 +73,10 @@ __decorate([
     }),
     __metadata("design:type", String)
 ], KycProofOfAddressCompletedV1.prototype, "occurredAt", 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)
+], KycProofOfAddressCompletedV1.prototype, "attemptId", void 0);

package/bin/kyc/events/KycStepCompletedV1.d.ts

@@ -1,3 +1,4 @@
+import { KycFlowEnum } from '../enums/KycFlowEnum';
 import { KycSubCheckNameEnum } from '../enums/KycSubCheckNameEnum';
 import { KycSubCheckStatusEnum } from '../enums/KycSubCheckStatusEnum';
 import { KycWatchlistStatusEnum } from '../enums/KycWatchlistStatusEnum';
@@ -82,4 +83,8 @@ export declare class KycStepCompletedV1 {
     occurredAt: string;
     /** El flujo de Metamap que corrió. Solo para diagnóstico — nadie ramifica por él. */
     metamapFlowId?: string;
+    /** Intento del wizard que originó la verificación; el consumidor descarta los que no son el vigente. */
+    attemptId?: string;
+    /** Flujo al que pertenece la estación, derivado de `metadata.kycStep`. */
+    flow?: KycFlowEnum;
 }

package/bin/kyc/events/KycStepCompletedV1.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.KycStepCompletedV1 = void 0;
 const class_transformer_1 = require("class-transformer");
 const class_validator_1 = require("class-validator");
+const KycFlowEnum_1 = require("../enums/KycFlowEnum");
 const KycSubCheckNameEnum_1 = require("../enums/KycSubCheckNameEnum");
 const IsKycStepStatusByStep_1 = require("../validators/IsKycStepStatusByStep");
 /**
@@ -91,3 +92,16 @@ __decorate([
     (0, class_validator_1.IsString)(),
     __metadata("design:type", String)
 ], KycStepCompletedV1.prototype, "metamapFlowId", 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)
+], KycStepCompletedV1.prototype, "attemptId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(KycFlowEnum_1.KycFlowEnum),
+    __metadata("design:type", String)
+], KycStepCompletedV1.prototype, "flow", void 0);

package/bin/kyc/events/KycVerificationChangedV1.d.ts

@@ -71,4 +71,6 @@ export declare class KycVerificationChangedV1 {
      * degradación segura (el consumidor lo pide y lo guarda él).
      */
     addressPushedToFiado?: boolean;
+    /** Intento del wizard que originó la verificación; el consumidor descarta los que no son el vigente. */
+    attemptId?: string;
 }

package/bin/kyc/events/KycVerificationChangedV1.js

@@ -104,3 +104,10 @@ __decorate([
     (0, class_validator_1.IsBoolean)(),
     __metadata("design:type", Boolean)
 ], KycVerificationChangedV1.prototype, "addressPushedToFiado", 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)
+], KycVerificationChangedV1.prototype, "attemptId", void 0);

package/bin/kyc/events/KycVerificationProgressV1.d.ts

@@ -0,0 +1,14 @@
+import { KycFlowEnum } from '../enums/KycFlowEnum';
+import { KycProgressStageEnum } from '../enums/KycProgressStageEnum';
+/** Avance de una verificación de Metamap (started, inputs_completed, expired) que publica `kyc-metamap-webhook`. */
+export declare class KycVerificationProgressV1 {
+    eventType: 'KycVerificationProgressV1';
+    stage: KycProgressStageEnum;
+    flow: KycFlowEnum;
+    verificationId: string;
+    directoryId: string;
+    /** Intento del wizard que originó la verificación; ausente en sesiones previas al despliegue. */
+    attemptId?: string;
+    /** ISO-8601 en UTC con `Z`, igual que los demás eventos de la cola. */
+    occurredAt: string;
+}

package/bin/kyc/events/KycVerificationProgressV1.js

@@ -0,0 +1,63 @@
+"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.KycVerificationProgressV1 = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const KycFlowEnum_1 = require("../enums/KycFlowEnum");
+const KycProgressStageEnum_1 = require("../enums/KycProgressStageEnum");
+/** Avance de una verificación de Metamap (started, inputs_completed, expired) que publica `kyc-metamap-webhook`. */
+class KycVerificationProgressV1 {
+}
+exports.KycVerificationProgressV1 = KycVerificationProgressV1;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsIn)(['KycVerificationProgressV1']),
+    __metadata("design:type", String)
+], KycVerificationProgressV1.prototype, "eventType", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(KycProgressStageEnum_1.KycProgressStageEnum),
+    __metadata("design:type", String)
+], KycVerificationProgressV1.prototype, "stage", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(KycFlowEnum_1.KycFlowEnum),
+    __metadata("design:type", String)
+], KycVerificationProgressV1.prototype, "flow", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], KycVerificationProgressV1.prototype, "verificationId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], KycVerificationProgressV1.prototype, "directoryId", 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)
+], KycVerificationProgressV1.prototype, "attemptId", 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-10-28T10:05:00.000Z)',
+    }),
+    __metadata("design:type", String)
+], KycVerificationProgressV1.prototype, "occurredAt", void 0);

package/bin/kyc/index.d.ts

@@ -3,6 +3,8 @@ export * from './enums/KycSubCheckStatusEnum';
 export * from './enums/KycWatchlistStatusEnum';
 export * from './enums/KycSubCheckNameEnum';
 export * from './enums/ProofAddressStatusEnum';
+export * from './enums/KycProgressStageEnum';
+export * from './enums/KycFlowEnum';
 export * from './dtos/KycSubChecks';
 export * from './validators/IsKycStepStatusByStep';
 export * from './helpers/applyKycStep';
@@ -12,3 +14,4 @@ export * from './dtos/responses/KycByDirectoryResponse';
 export * from './events/KycVerificationChangedV1';
 export * from './events/KycStepCompletedV1';
 export * from './events/KycProofOfAddressCompletedV1';
+export * from './events/KycVerificationProgressV1';

package/bin/kyc/index.js

@@ -21,6 +21,8 @@ __exportStar(require("./enums/KycSubCheckStatusEnum"), exports);
 __exportStar(require("./enums/KycWatchlistStatusEnum"), exports);
 __exportStar(require("./enums/KycSubCheckNameEnum"), exports);
 __exportStar(require("./enums/ProofAddressStatusEnum"), exports);
+__exportStar(require("./enums/KycProgressStageEnum"), exports);
+__exportStar(require("./enums/KycFlowEnum"), exports);
 // Sub-pasos descompuestos (SureKeep F2)
 __exportStar(require("./dtos/KycSubChecks"), exports);
 // Validators
@@ -36,3 +38,4 @@ __exportStar(require("./dtos/responses/KycByDirectoryResponse"), exports);
 __exportStar(require("./events/KycVerificationChangedV1"), exports);
 __exportStar(require("./events/KycStepCompletedV1"), exports);
 __exportStar(require("./events/KycProofOfAddressCompletedV1"), exports);
+__exportStar(require("./events/KycVerificationProgressV1"), exports);

package/bin/retailWizard/dtos/KycAttemptProgress.d.ts

@@ -0,0 +1,14 @@
+import { KycModalityEnum } from '../../retailCustomer/enums/KycModalityEnum';
+import { KycAttemptStageEnum } from '../enums/KycAttemptStageEnum';
+/** Avance del intento vigente de un flujo KYC, tal como lo devuelve `GET kyc/status`. */
+export interface KycAttemptProgress {
+    attemptId: string;
+    modality: KycModalityEnum.CUSTOMER_LINK | KycModalityEnum.STORE_DEVICE;
+    /** `shortUrl` del QR; ausente en `STORE_DEVICE`. */
+    link?: string;
+    stage: KycAttemptStageEnum;
+    /** Cuándo entró a la etapa actual, ISO-8601 UTC. */
+    stageAt: string;
+    /** Fecha del prepare, ISO-8601 UTC; el front mide contra ella el tope de 25 min. */
+    attemptStartedAt: string;
+}

package/bin/retailWizard/dtos/KycAttemptProgress.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/retailWizard/dtos/KycStatusProgress.d.ts

@@ -0,0 +1,7 @@
+import type { KycAttemptProgress } from './KycAttemptProgress';
+/** Bloque `progress` de `GET kyc/status`: el intento vigente de cada flujo, o `null` si no hay. */
+export interface KycStatusProgress {
+    identity: KycAttemptProgress | null;
+    facematch: KycAttemptProgress | null;
+    proofOfAddress: KycAttemptProgress | null;
+}

package/bin/retailWizard/dtos/KycStatusProgress.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/bin/retailWizard/dtos/responses/KycPrepareResponse.d.ts

@@ -52,6 +52,8 @@ export interface KycSdkMetadata {
      * domicilio del documento de identidad: `kyc-metamap-webhook` rutea por este campo.
      */
     kycStep?: KycMetadataStepEnum;
+    /** Intento del wizard que originó la verificación; el webhook lo copia a cada evento. */
+    attemptId?: string;
 }
 /**
  * Paso del onboarding que originó una verificación, tal como viaja en `KycSdkMetadata.kycStep`.
@@ -94,6 +96,8 @@ export interface KycPrepareResponse {
      * (`KycManualRequest`). Por eso el tipo se estrecha a las dos que el SDK puede ejecutar.
      */
     modality: KycModalityEnum.CUSTOMER_LINK | KycModalityEnum.STORE_DEVICE;
+    /** Intento que abrió este prepare; ausente cuando no se crea intento: alreadyVerified o bypass de dev. */
+    attemptId?: string;
     /** STORE_DEVICE — clientId de la cuenta Metamap (mismo valor en prod y dev). */
     clientId?: string;
     /** STORE_DEVICE — flow de Metamap por país; sale de la configuración del wizard. */

package/bin/retailWizard/dtos/responses/ProofOfAddressPrepareResponse.d.ts

@@ -13,6 +13,8 @@ import { KycModalityEnum } from '../../../retailCustomer/enums/KycModalityEnum';
 export interface ProofOfAddressPrepareResponse {
     /** `MANUAL` no es una modalidad de `prepare`: la captura manual es su propio endpoint. */
     modality: KycModalityEnum.CUSTOMER_LINK | KycModalityEnum.STORE_DEVICE;
+    /** Intento que abrió este prepare; ausente cuando alreadyHasAddress. */
+    attemptId?: string;
     /** STORE_DEVICE — clientId de la cuenta Metamap (mismo valor en prod y dev). */
     clientId?: string;
     /** STORE_DEVICE — flow de Metamap del comprobante de domicilio. */

package/bin/retailWizard/enums/KycAttemptStageEnum.d.ts

@@ -0,0 +1,8 @@
+/** Etapa del intento vigente de un flujo KYC del wizard; el rango de monotonía vive en el wizard. */
+export declare enum KycAttemptStageEnum {
+    AWAITING_START = "AWAITING_START",
+    STARTED = "STARTED",
+    INPUTS_COMPLETED = "INPUTS_COMPLETED",
+    EXPIRED = "EXPIRED",
+    RESULT = "RESULT"
+}

package/bin/retailWizard/enums/KycAttemptStageEnum.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KycAttemptStageEnum = void 0;
+/** Etapa del intento vigente de un flujo KYC del wizard; el rango de monotonía vive en el wizard. */
+var KycAttemptStageEnum;
+(function (KycAttemptStageEnum) {
+    KycAttemptStageEnum["AWAITING_START"] = "AWAITING_START";
+    KycAttemptStageEnum["STARTED"] = "STARTED";
+    KycAttemptStageEnum["INPUTS_COMPLETED"] = "INPUTS_COMPLETED";
+    KycAttemptStageEnum["EXPIRED"] = "EXPIRED";
+    KycAttemptStageEnum["RESULT"] = "RESULT";
+})(KycAttemptStageEnum || (exports.KycAttemptStageEnum = KycAttemptStageEnum = {}));

package/bin/retailWizard/index.d.ts

@@ -33,6 +33,7 @@ export * from './enums/LinePaymentTypeEnum';
 export * from './enums/WizardLineRoleEnum';
 export * from './enums/EmailStateEnum';
 export * from './enums/SaleChannelEnum';
+export * from './enums/KycAttemptStageEnum';
 export * from './dtos/WizardConsents';
 export * from './dtos/WizardPayment';
 export * from './dtos/WizardProduct';
@@ -57,6 +58,8 @@ export * from './dtos/WizardReservedLine';
 export * from './dtos/WizardGiftLine';
 export * from './dtos/SaleLine';
 export * from './dtos/AccessorySaleLine';
+export * from './dtos/KycAttemptProgress';
+export * from './dtos/KycStatusProgress';
 export * from './dtos/WizardSession';
 export * from './dtos/OtpVerification';
 export * from './dtos/Sale';

package/bin/retailWizard/index.js

@@ -52,6 +52,7 @@ __exportStar(require("./enums/LinePaymentTypeEnum"), exports);
 __exportStar(require("./enums/WizardLineRoleEnum"), exports);
 __exportStar(require("./enums/EmailStateEnum"), exports);
 __exportStar(require("./enums/SaleChannelEnum"), exports);
+__exportStar(require("./enums/KycAttemptStageEnum"), exports);
 // DTOs anidados
 __exportStar(require("./dtos/WizardConsents"), exports);
 __exportStar(require("./dtos/WizardPayment"), exports);
@@ -79,6 +80,8 @@ __exportStar(require("./dtos/WizardReservedLine"), exports);
 __exportStar(require("./dtos/WizardGiftLine"), exports);
 __exportStar(require("./dtos/SaleLine"), exports);
 __exportStar(require("./dtos/AccessorySaleLine"), exports);
+__exportStar(require("./dtos/KycAttemptProgress"), exports);
+__exportStar(require("./dtos/KycStatusProgress"), exports);
 // Entidades principales (shapes de estado/persistencia — planas)
 __exportStar(require("./dtos/WizardSession"), exports);
 __exportStar(require("./dtos/OtpVerification"), exports);

package/package.json

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

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

@@ -138,6 +138,10 @@ export class BiometricVerificationResponse {
     @Expose() @IsISO8601({ strict: true })
     expiresAt!: string;
 
+    /** Cuándo el usuario terminó de subir su información. ISO-8601 UTC con `Z`; ausente si aún no. */
+    @Expose() @IsOptional() @IsISO8601({ strict: true })
+    inputsCompletedAt?: string;
+
     /** Cuándo alcanzó un estado terminal. Ausente mientras siga viva. */
     @Expose() @IsOptional() @IsISO8601({ strict: true })
     completedAt?: string;

package/src/biometrics/enums/BiometricEventTypeEnum.ts

@@ -3,8 +3,8 @@
  * 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.
+ * estos valores 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 valores.
  *
  * `biometrics-business` — Entrega 1.
  */
@@ -28,4 +28,10 @@ export enum BiometricEventTypeEnum {
      * contra `expiresAt` (DEC-015), así que una verificación vence aunque este evento nunca llegue.
      */
     VERIFICATION_EXPIRED = 'VERIFICATION_EXPIRED',
+
+    /** El usuario terminó de subir su información. Sigue en `IN_PROGRESS` y graba `inputsCompletedAt`. */
+    INPUTS_COMPLETED = 'INPUTS_COMPLETED',
+
+    /** El proveedor cambió el veredicto (revisión manual). Se trata igual que `VERIFICATION_COMPLETED`. */
+    UPDATED = 'UPDATED',
 }

package/src/kyc/enums/KycFlowEnum.ts

@@ -0,0 +1,5 @@
+/** Flujo de Metamap al que pertenece un evento; el webhook lo deriva de `metadata.kycStep`. */
+export enum KycFlowEnum {
+    IDENTITY = 'IDENTITY',
+    PROOF_OF_ADDRESS = 'PROOF_OF_ADDRESS',
+}

package/src/kyc/enums/KycProgressStageEnum.ts

@@ -0,0 +1,6 @@
+/** Etapa de avance de una verificación de Metamap, tal como la publica `kyc-metamap-webhook`. */
+export enum KycProgressStageEnum {
+    STARTED = 'STARTED',
+    INPUTS_COMPLETED = 'INPUTS_COMPLETED',
+    EXPIRED = 'EXPIRED',
+}

package/src/kyc/events/KycProofOfAddressCompletedV1.ts

@@ -65,4 +65,8 @@ export class KycProofOfAddressCompletedV1 {
         message: 'occurredAt debe ser ISO-8601 en UTC con Z (ej. 2026-08-11T10:05:00.000Z): un offset rompe el orden léxico',
     })
     occurredAt!: string;
+
+    /** Intento del wizard que originó el comprobante; el consumidor descarta los que no son el vigente. */
+    @Expose() @IsOptional() @IsString() @IsNotEmpty()
+    attemptId?: string;
 }

package/src/kyc/events/KycStepCompletedV1.ts

@@ -1,5 +1,6 @@
 import { Expose } from 'class-transformer';
 import { IsEnum, IsIn, IsISO8601, IsNotEmpty, IsOptional, IsString, Matches, Validate } from 'class-validator';
+import { KycFlowEnum } from '../enums/KycFlowEnum';
 import { KycSubCheckNameEnum } from '../enums/KycSubCheckNameEnum';
 import { KycSubCheckStatusEnum } from '../enums/KycSubCheckStatusEnum';
 import { KycWatchlistStatusEnum } from '../enums/KycWatchlistStatusEnum';
@@ -102,4 +103,12 @@ export class KycStepCompletedV1 {
     /** El flujo de Metamap que corrió. Solo para diagnóstico — nadie ramifica por él. */
     @Expose() @IsOptional() @IsString()
     metamapFlowId?: string;
+
+    /** Intento del wizard que originó la verificación; el consumidor descarta los que no son el vigente. */
+    @Expose() @IsOptional() @IsString() @IsNotEmpty()
+    attemptId?: string;
+
+    /** Flujo al que pertenece la estación, derivado de `metadata.kycStep`. */
+    @Expose() @IsOptional() @IsEnum(KycFlowEnum)
+    flow?: KycFlowEnum;
 }

package/src/kyc/events/KycVerificationChangedV1.ts

@@ -95,4 +95,8 @@ export class KycVerificationChangedV1 {
      */
     @Expose() @IsOptional() @IsBoolean()
     addressPushedToFiado?: boolean;
+
+    /** Intento del wizard que originó la verificación; el consumidor descarta los que no son el vigente. */
+    @Expose() @IsOptional() @IsString() @IsNotEmpty()
+    attemptId?: string;
 }

package/src/kyc/events/KycVerificationProgressV1.ts

@@ -0,0 +1,33 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsIn, IsISO8601, IsNotEmpty, IsOptional, IsString, Matches } from 'class-validator';
+import { KycFlowEnum } from '../enums/KycFlowEnum';
+import { KycProgressStageEnum } from '../enums/KycProgressStageEnum';
+
+/** Avance de una verificación de Metamap (started, inputs_completed, expired) que publica `kyc-metamap-webhook`. */
+export class KycVerificationProgressV1 {
+    @Expose() @IsIn(['KycVerificationProgressV1'])
+    eventType!: 'KycVerificationProgressV1';
+
+    @Expose() @IsEnum(KycProgressStageEnum)
+    stage!: KycProgressStageEnum;
+
+    @Expose() @IsEnum(KycFlowEnum)
+    flow!: KycFlowEnum;
+
+    @Expose() @IsString() @IsNotEmpty()
+    verificationId!: string;
+
+    @Expose() @IsString() @IsNotEmpty()
+    directoryId!: string;
+
+    /** Intento del wizard que originó la verificación; ausente en sesiones previas al despliegue. */
+    @Expose() @IsOptional() @IsString() @IsNotEmpty()
+    attemptId?: string;
+
+    /** ISO-8601 en UTC con `Z`, igual que los demás eventos de la cola. */
+    @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-10-28T10:05:00.000Z)',
+    })
+    occurredAt!: string;
+}

package/src/kyc/index.ts

@@ -5,6 +5,8 @@ export * from './enums/KycSubCheckStatusEnum';
 export * from './enums/KycWatchlistStatusEnum';
 export * from './enums/KycSubCheckNameEnum';
 export * from './enums/ProofAddressStatusEnum';
+export * from './enums/KycProgressStageEnum';
+export * from './enums/KycFlowEnum';
 
 // Sub-pasos descompuestos (SureKeep F2)
 export * from './dtos/KycSubChecks';
@@ -26,3 +28,4 @@ export * from './dtos/responses/KycByDirectoryResponse';
 export * from './events/KycVerificationChangedV1';
 export * from './events/KycStepCompletedV1';
 export * from './events/KycProofOfAddressCompletedV1';
+export * from './events/KycVerificationProgressV1';

package/src/retailWizard/dtos/KycAttemptProgress.ts

@@ -0,0 +1,15 @@
+import { KycModalityEnum } from '../../retailCustomer/enums/KycModalityEnum';
+import { KycAttemptStageEnum } from '../enums/KycAttemptStageEnum';
+
+/** Avance del intento vigente de un flujo KYC, tal como lo devuelve `GET kyc/status`. */
+export interface KycAttemptProgress {
+    attemptId: string;
+    modality: KycModalityEnum.CUSTOMER_LINK | KycModalityEnum.STORE_DEVICE;
+    /** `shortUrl` del QR; ausente en `STORE_DEVICE`. */
+    link?: string;
+    stage: KycAttemptStageEnum;
+    /** Cuándo entró a la etapa actual, ISO-8601 UTC. */
+    stageAt: string;
+    /** Fecha del prepare, ISO-8601 UTC; el front mide contra ella el tope de 25 min. */
+    attemptStartedAt: string;
+}

package/src/retailWizard/dtos/KycStatusProgress.ts

@@ -0,0 +1,8 @@
+import type { KycAttemptProgress } from './KycAttemptProgress';
+
+/** Bloque `progress` de `GET kyc/status`: el intento vigente de cada flujo, o `null` si no hay. */
+export interface KycStatusProgress {
+    identity: KycAttemptProgress | null;
+    facematch: KycAttemptProgress | null;
+    proofOfAddress: KycAttemptProgress | null;
+}

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

@@ -53,6 +53,8 @@ export interface KycSdkMetadata {
      * domicilio del documento de identidad: `kyc-metamap-webhook` rutea por este campo.
      */
     kycStep?: KycMetadataStepEnum;
+    /** Intento del wizard que originó la verificación; el webhook lo copia a cada evento. */
+    attemptId?: string;
 }
 
 /**
@@ -98,6 +100,8 @@ export interface KycPrepareResponse {
      * (`KycManualRequest`). Por eso el tipo se estrecha a las dos que el SDK puede ejecutar.
      */
     modality: KycModalityEnum.CUSTOMER_LINK | KycModalityEnum.STORE_DEVICE;
+    /** Intento que abrió este prepare; ausente cuando no se crea intento: alreadyVerified o bypass de dev. */
+    attemptId?: string;
     /** STORE_DEVICE — clientId de la cuenta Metamap (mismo valor en prod y dev). */
     clientId?: string;
     /** STORE_DEVICE — flow de Metamap por país; sale de la configuración del wizard. */

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

@@ -14,6 +14,8 @@ import { KycModalityEnum } from '../../../retailCustomer/enums/KycModalityEnum';
 export interface ProofOfAddressPrepareResponse {
     /** `MANUAL` no es una modalidad de `prepare`: la captura manual es su propio endpoint. */
     modality: KycModalityEnum.CUSTOMER_LINK | KycModalityEnum.STORE_DEVICE;
+    /** Intento que abrió este prepare; ausente cuando alreadyHasAddress. */
+    attemptId?: string;
     /** STORE_DEVICE — clientId de la cuenta Metamap (mismo valor en prod y dev). */
     clientId?: string;
     /** STORE_DEVICE — flow de Metamap del comprobante de domicilio. */

package/src/retailWizard/enums/KycAttemptStageEnum.ts

@@ -0,0 +1,8 @@
+/** Etapa del intento vigente de un flujo KYC del wizard; el rango de monotonía vive en el wizard. */
+export enum KycAttemptStageEnum {
+    AWAITING_START = 'AWAITING_START',
+    STARTED = 'STARTED',
+    INPUTS_COMPLETED = 'INPUTS_COMPLETED',
+    EXPIRED = 'EXPIRED',
+    RESULT = 'RESULT',
+}

package/src/retailWizard/index.ts

@@ -36,6 +36,7 @@ export * from './enums/LinePaymentTypeEnum';
 export * from './enums/WizardLineRoleEnum';
 export * from './enums/EmailStateEnum';
 export * from './enums/SaleChannelEnum';
+export * from './enums/KycAttemptStageEnum';
 
 // DTOs anidados
 export * from './dtos/WizardConsents';
@@ -62,6 +63,8 @@ export * from './dtos/WizardReservedLine';
 export * from './dtos/WizardGiftLine';
 export * from './dtos/SaleLine';
 export * from './dtos/AccessorySaleLine';
+export * from './dtos/KycAttemptProgress';
+export * from './dtos/KycStatusProgress';
 
 // Entidades principales (shapes de estado/persistencia — planas)
 export * from './dtos/WizardSession';