@fiado/type-kit 3.218.0 → 3.220.0

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

@@ -0,0 +1,86 @@
+import 'reflect-metadata';
+import { ValidationArguments } from 'class-validator';
+import {
+  IsKycStepStatusByStep,
+  KycSubCheckNameEnum,
+} from '../../../src/kyc/index';
+
+/**
+ * Tests del validador AISLADO — sin pasar por el DTO. `KycStepCompletedV1.test.ts` ya prueba el
+ * cruce estación ↔ vocabulario a través del boundary; acá se ejercen las entradas degeneradas y el
+ * `defaultMessage()`, que desde el DTO no se alcanzan.
+ */
+const validador = new IsKycStepStatusByStep();
+
+const args = (step: unknown): ValidationArguments =>
+  ({ object: { step }, value: undefined, targetName: '', property: 'status', constraints: [] });
+
+describe('IsKycStepStatusByStep', () => {
+  describe('validate — entradas que no son un status', () => {
+    // Un `''` o un `'   '` no es un status: sin este candado, `includes` los rechaza hoy por
+    // casualidad, pero nada impide que alguien agregue un `.trim()` permisivo mañana.
+    it.each([
+      ['string vacío', ''],
+      ['whitespace puro', '   '],
+      ['número', 123],
+      ['null', null],
+      ['undefined', undefined],
+      ['objeto', { status: 'PASS' }],
+      ['array', ['PASS']],
+    ])('rechaza %s', (_etiqueta, valor) => {
+      expect(validador.validate(valor, args(KycSubCheckNameEnum.FACEMATCH))).toBe(false);
+    });
+
+    // Los enums viajan en MAYÚSCULAS. Aceptar 'pass' abriría la puerta a que dos repos escriban
+    // el mismo estado de dos formas y el consumidor tenga que normalizar.
+    it.each(['pass', 'Pass', 'fail', 'clear', 'Hit'])('rechaza %s (el casing importa)', (valor) => {
+      const step = valor.toLowerCase() === 'clear' || valor.toLowerCase() === 'hit'
+        ? KycSubCheckNameEnum.WATCHLISTS
+        : KycSubCheckNameEnum.FACEMATCH;
+
+      expect(validador.validate(valor, args(step))).toBe(false);
+    });
+  });
+
+  describe('validate — sin estación reconocida no hay vocabulario', () => {
+    it.each([
+      ['step ausente', undefined],
+      ['step inventado', 'inventado'],
+      ['step que Metamap emite pero no está en el contrato', 'selfie'],
+      ['step no-string', 42],
+    ])('rechaza cualquier status con %s', (_etiqueta, step) => {
+      expect(validador.validate('PASS', args(step))).toBe(false);
+      expect(validador.validate('CLEAR', args(step))).toBe(false);
+    });
+  });
+
+  describe('defaultMessage — las tres ramas', () => {
+    it('en una estación de lista nombra CLEAR/HIT y explica que un HIT no es un fallo', () => {
+      const msg = validador.defaultMessage(args(KycSubCheckNameEnum.WATCHLISTS));
+
+      expect(msg).toContain('CLEAR');
+      expect(msg).toContain('HIT');
+      expect(msg).toContain('watchlists');
+      expect(msg).not.toContain('PASS');
+    });
+
+    it('en una estación binaria nombra PASS/FAIL', () => {
+      const msg = validador.defaultMessage(args(KycSubCheckNameEnum.LIVENESS));
+
+      expect(msg).toContain('PASS');
+      expect(msg).toContain('FAIL');
+      expect(msg).toContain('liveness');
+      expect(msg).not.toContain('CLEAR');
+    });
+
+    // La rama que ningún test del DTO alcanza: sin step reconocido el mensaje no puede nombrar
+    // un vocabulario, y decir "debe ser PASS o FAIL" ahí sería mentir.
+    it('sin estación reconocida dice que no se puede validar, sin inventar un vocabulario', () => {
+      const msg = validador.defaultMessage(args('inventado'));
+
+      expect(msg).toContain('step');
+      expect(msg).not.toContain('PASS');
+      expect(msg).not.toContain('CLEAR');
+    });
+  });
+});

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

@@ -0,0 +1,239 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+  KycStepCompletedV1,
+  KycVerificationChangedV1,
+  KycSubCheckNameEnum,
+  KycSubCheckStatusEnum,
+  KycWatchlistStatusEnum,
+  KYC_WATCHLIST_STEPS,
+} from '../../../src/kyc/index';
+
+/** Base válida de una estación binaria; cada caso pisa solo el campo que está probando. */
+const base = {
+  verificationId: 'ver-1',
+  directoryId: 'dir-1',
+  step: 'facematch',
+  status: 'PASS',
+  occurredAt: '2026-07-26T10:05:00.000Z',
+};
+
+const instancia = (raw: Record<string, unknown>): KycStepCompletedV1 =>
+  plainToInstance(KycStepCompletedV1, raw, { excludeExtraneousValues: true });
+
+describe('KycStepCompletedV1', () => {
+  it('valida el shape que publica el webhook desde un step_completed', async () => {
+    const dto = instancia({ ...base, metamapFlowId: 'flow-1' });
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.step).toBe(KycSubCheckNameEnum.FACEMATCH);
+    expect(dto.status).toBe(KycSubCheckStatusEnum.PASS);
+  });
+
+  it('valida sin metamapFlowId (es opcional, solo diagnóstico)', async () => {
+    const dto = instancia(base);
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.metamapFlowId).toBeUndefined();
+  });
+
+  // Sin directoryId el consumidor no puede encontrar la sesión: el evento no sirve para nada.
+  it('rechaza un evento sin directoryId (sin él no hay gate posible)', async () => {
+    const { directoryId: _omitido, ...sinDirectory } = base;
+    const errors = await validate(instancia(sinDirectory) as object);
+
+    expect(errors.map((e) => e.property)).toContain('directoryId');
+  });
+
+  // DEC-KYC-015: un '' pasa @IsString() en silencio y falla tres pasos río abajo.
+  it.each(['verificationId', 'directoryId'])('rechaza %s vacío', async (campo) => {
+    const errors = await validate(instancia({ ...base, [campo]: '' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain(campo);
+  });
+
+  // Candado del contrato: solo viajan las 8 estaciones de KycSubChecks. Metamap emite 13 —
+  // 'selfie', 'voice', 'ipValidation' y compañía NO forman parte del contrato. Sin esto, el
+  // campo se podría degradar a @IsString() y una estación desconocida llegaría al progreso.
+  it('rechaza una estación que Metamap emite pero NO está en el contrato', async () => {
+    const errors = await validate(instancia({ ...base, step: 'selfie' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('step');
+  });
+
+  // ── El cruce step ↔ status: la razón de ser del validador custom ───────────
+
+  it.each(KYC_WATCHLIST_STEPS)('acepta CLEAR y HIT en la estación de lista %s', async (step) => {
+    const clear = await validate(instancia({ ...base, step, status: 'CLEAR' }) as object);
+    const hit = await validate(instancia({ ...base, step, status: 'HIT' }) as object);
+
+    expect(clear).toHaveLength(0);
+    expect(hit).toHaveLength(0);
+  });
+
+  /**
+   * El candado que justifica el validador. Un `@IsIn(['PASS','FAIL','CLEAR','HIT'])` dejaría pasar
+   * esto y el matiz se perdería: un HIT es "que lo mire cumplimiento", no una falla. Con este evento
+   * colado, la pantalla del vendedor marcaría como fallida una estación que solo pide revisión.
+   */
+  it.each(KYC_WATCHLIST_STEPS)('rechaza FAIL en la estación de lista %s (un HIT no es un fallo)', async (step) => {
+    const errors = await validate(instancia({ ...base, step, status: 'FAIL' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('status');
+  });
+
+  const BINARIOS = Object.values(KycSubCheckNameEnum).filter((s) => !KYC_WATCHLIST_STEPS.includes(s));
+
+  it.each(BINARIOS)('acepta PASS y FAIL en la estación binaria %s', async (step) => {
+    const pass = await validate(instancia({ ...base, step, status: 'PASS' }) as object);
+    const fail = await validate(instancia({ ...base, step, status: 'FAIL' }) as object);
+
+    expect(pass).toHaveLength(0);
+    expect(fail).toHaveLength(0);
+  });
+
+  it.each(BINARIOS)('rechaza HIT en la estación binaria %s', async (step) => {
+    const errors = await validate(instancia({ ...base, step, status: 'HIT' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('status');
+  });
+
+  it('rechaza un status inventado', async () => {
+    const errors = await validate(instancia({ ...base, status: 'MAS_O_MENOS' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('status');
+  });
+
+  // Con un step inválido no hay vocabulario contra el cual medir el status: fallan los dos.
+  it('rechaza el status cuando el step no es reconocido', async () => {
+    const errors = await validate(instancia({ ...base, step: 'inventado' }) as object);
+
+    expect(errors.map((e) => e.property)).toEqual(expect.arrayContaining(['step', 'status']));
+  });
+
+  // ── Orden ─────────────────────────────────────────────────────────────────
+
+  /**
+   * SQS estándar no garantiza orden. El consumidor descarta las estaciones que llegan más viejas
+   * que lo que ya escribió, y para eso `occurredAt` tiene que ser léxicamente ordenable.
+   */
+  it('rechaza occurredAt con formato no ISO-8601', async () => {
+    const errors = await validate(instancia({ ...base, occurredAt: '26/07/2026' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('occurredAt');
+  });
+
+  it('rechaza un evento sin occurredAt (sin marca de tiempo no hay cómo ordenar)', async () => {
+    const { occurredAt: _omitido, ...sinFecha } = base;
+    const errors = await validate(instancia(sinFecha) as object);
+
+    expect(errors.map((e) => e.property)).toContain('occurredAt');
+  });
+
+  /**
+   * `@IsISO8601()` a secas acepta TODOS estos, y cada uno rompe la comparación léxica de distinta
+   * forma. El offset es el peligroso: `T15:05:00+05:00` son las 10:05 UTC, pero léxicamente es
+   * "mayor" que un `T10:06:00Z` posterior — el consumidor lo lee como más nuevo, descarta la
+   * estación real y esa casilla nunca se pinta. Sin este candado el `@Matches` se puede quitar y
+   * la suite sigue verde.
+   */
+  it.each([
+    ['offset positivo en vez de Z', '2026-07-26T15:05:00+05:00'],
+    ['offset negativo en vez de Z', '2026-07-26T05:05:00-05:00'],
+    ['solo fecha, sin hora', '2026-07-26'],
+    ['formato básico sin guiones', '20260726T100500Z'],
+    ['fecha de semana ISO', '2026-W30-1'],
+    ['fecha imposible', '2026-02-30T10:05:00.000Z'],
+    ['sin zona horaria', '2026-07-26T10:05:00'],
+  ])('rechaza occurredAt %s', async (_etiqueta, valor) => {
+    const errors = await validate(instancia({ ...base, occurredAt: valor }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('occurredAt');
+  });
+
+  it.each([
+    ['con milisegundos', '2026-07-26T10:05:00.000Z'],
+    ['sin milisegundos', '2026-07-26T10:05:00Z'],
+  ])('acepta occurredAt en UTC %s', async (_etiqueta, valor) => {
+    expect(await validate(instancia({ ...base, occurredAt: valor }) as object)).toHaveLength(0);
+  });
+
+  // ── eventType: el discriminador explícito ─────────────────────────────────
+
+  it('acepta el eventType explícito', async () => {
+    const dto = instancia({ ...base, eventType: 'KycStepCompletedV1' });
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.eventType).toBe('KycStepCompletedV1');
+  });
+
+  // Opcional a propósito: agregarlo ahora es gratis, hacerlo obligatorio después del primer
+  // deploy sería breaking. Este candado prueba que hoy NO lo es.
+  it('valida sin eventType (es opcional para no romper al webhook antes de que lo mande)', async () => {
+    const dto = instancia(base);
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.eventType).toBeUndefined();
+  });
+
+  // Si el día de mañana llega un `KycStepStartedV1`, tiene que caer como "no soportado" en el
+  // ruteo, no colarse por esta rama y morir en el DLQ como "corrupto".
+  it('rechaza un eventType de otro evento', async () => {
+    const errors = await validate(instancia({ ...base, eventType: 'KycStepStartedV1' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('eventType');
+  });
+
+  // ── Convivencia en la misma cola ──────────────────────────────────────────
+
+  /**
+   * Los dos eventos comparten `RetailKycInboundQueue` y el discriminador es la presencia de `step`.
+   * Estos dos candados prueban que un evento NO se puede hacer pasar por el otro: si alguien
+   * agregara campos que los volvieran mutuamente válidos, el consumidor tomaría la rama equivocada
+   * y el cierre de la verificación se procesaría como una estación suelta (o al revés).
+   */
+  it('un cierre de verificación NO valida como evento de estación', async () => {
+    const cierre = {
+      verificationId: 'ver-1', directoryId: 'dir-1', peopleId: 'ppl-1',
+      verificationStatus: 'COMPLETED', verificationResult: 'VERIFIED',
+      updateDate: '2026-07-26T10:05:00.000Z',
+    };
+
+    const errors = await validate(instancia(cierre) as object);
+
+    expect(errors.map((e) => e.property)).toEqual(expect.arrayContaining(['step', 'status', 'occurredAt']));
+  });
+
+  it('un evento de estación NO valida como cierre de verificación', async () => {
+    const dto = plainToInstance(KycVerificationChangedV1, base, { excludeExtraneousValues: true });
+    const errors = await validate(dto as object);
+
+    expect(errors.map((e) => e.property)).toEqual(
+      expect.arrayContaining(['peopleId', 'verificationStatus', 'verificationResult', 'updateDate']),
+    );
+  });
+
+  // ── El contrato con KycSubChecks ──────────────────────────────────────────
+
+  /**
+   * El consumidor arma el progreso con `progreso[evento.step] = evento.status`. Si un valor del enum
+   * dejara de coincidir con su llave en `KycSubChecks`, escribiría un campo huérfano y esa estación
+   * nunca se marcaría — sin que nada truene. Este test es el único lugar donde eso se detecta.
+   */
+  it('cada valor del enum es una llave real de KycSubChecks', () => {
+    const llavesDeSubChecks = [
+      'documentReading', 'templateMatching', 'alterationDetection', 'facematch',
+      'liveness', 'ageCheck', 'watchlists', 'premiumAmlWatchlists',
+    ];
+
+    expect(Object.values(KycSubCheckNameEnum).sort()).toEqual(llavesDeSubChecks.sort());
+  });
+
+  it('las estaciones de lista son exactamente las dos que usan CLEAR/HIT', () => {
+    expect([...KYC_WATCHLIST_STEPS].sort()).toEqual(
+      [KycSubCheckNameEnum.PREMIUM_AML_WATCHLISTS, KycSubCheckNameEnum.WATCHLISTS].sort(),
+    );
+    expect(Object.values(KycWatchlistStatusEnum)).toEqual(['CLEAR', 'HIT']);
+  });
+});

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

@@ -0,0 +1,75 @@
+import 'reflect-metadata';
+import {
+  applyKycStep,
+  KycSubChecks,
+  KycSubCheckNameEnum,
+  KycSubCheckStatusEnum,
+  KycWatchlistStatusEnum,
+} from '../../../src/kyc/index';
+
+describe('applyKycStep', () => {
+  it('asienta la primera estación sobre un progreso inexistente', () => {
+    const progreso = applyKycStep(undefined, KycSubCheckNameEnum.FACEMATCH, KycSubCheckStatusEnum.PASS);
+
+    expect(progreso.facematch).toBe(KycSubCheckStatusEnum.PASS);
+  });
+
+  it('acumula estaciones sin borrar las anteriores', () => {
+    let progreso = applyKycStep(undefined, KycSubCheckNameEnum.DOCUMENT_READING, KycSubCheckStatusEnum.PASS);
+    progreso = applyKycStep(progreso, KycSubCheckNameEnum.LIVENESS, KycSubCheckStatusEnum.FAIL);
+    progreso = applyKycStep(progreso, KycSubCheckNameEnum.WATCHLISTS, KycWatchlistStatusEnum.HIT);
+
+    expect(progreso).toEqual({
+      documentReading: KycSubCheckStatusEnum.PASS,
+      liveness: KycSubCheckStatusEnum.FAIL,
+      watchlists: KycWatchlistStatusEnum.HIT,
+    });
+  });
+
+  /**
+   * No muta el objeto recibido. Importa porque el consumidor lee el progreso de la fila de sesión y
+   * lo vuelve a escribir: si el helper mutara, una comparación "¿cambió algo?" contra el objeto
+   * original siempre daría que no, y la escritura se saltaría.
+   */
+  it('devuelve un objeto nuevo y deja intacto el que recibe', () => {
+    const original: KycSubChecks = { documentReading: KycSubCheckStatusEnum.PASS };
+
+    const siguiente = applyKycStep(original, KycSubCheckNameEnum.LIVENESS, KycSubCheckStatusEnum.PASS);
+
+    expect(siguiente).not.toBe(original);
+    expect(original).toEqual({ documentReading: KycSubCheckStatusEnum.PASS });
+    expect(original.liveness).toBeUndefined();
+  });
+
+  // Una reentrega de SQS del mismo evento tiene que dejar el progreso igual: esa es toda la razón
+  // por la que el evento no necesita `eventId`.
+  it('es idempotente — reprocesar la misma estación no cambia nada', () => {
+    const una = applyKycStep(undefined, KycSubCheckNameEnum.AGE_CHECK, KycSubCheckStatusEnum.PASS);
+    const dos = applyKycStep(una, KycSubCheckNameEnum.AGE_CHECK, KycSubCheckStatusEnum.PASS);
+
+    expect(dos).toEqual(una);
+  });
+
+  it('un reintento del cliente pisa el resultado anterior de esa estación', () => {
+    const fallido = applyKycStep(undefined, KycSubCheckNameEnum.DOCUMENT_READING, KycSubCheckStatusEnum.FAIL);
+    const reintento = applyKycStep(fallido, KycSubCheckNameEnum.DOCUMENT_READING, KycSubCheckStatusEnum.PASS);
+
+    expect(reintento.documentReading).toBe(KycSubCheckStatusEnum.PASS);
+  });
+
+  /**
+   * El candado que justifica que el helper exista: la llave que escribe tiene que ser una propiedad
+   * REAL de `KycSubChecks`, para las 8. Si un valor del enum dejara de coincidir con su llave, el
+   * helper escribiría un campo huérfano y la estación nunca se marcaría, sin que nada truene.
+   */
+  it.each(Object.values(KycSubCheckNameEnum))('la estación %s cae en su llave real de KycSubChecks', (step) => {
+    const status = step === KycSubCheckNameEnum.WATCHLISTS || step === KycSubCheckNameEnum.PREMIUM_AML_WATCHLISTS
+      ? KycWatchlistStatusEnum.CLEAR
+      : KycSubCheckStatusEnum.PASS;
+
+    const progreso = applyKycStep(undefined, step, status);
+
+    expect(Object.keys(progreso)).toEqual([step]);
+    expect(progreso[step as keyof KycSubChecks]).toBe(status);
+  });
+});

package/bin/benefitCenter/enums/BenefitFlowEnum.d.ts

@@ -0,0 +1,11 @@
+export declare enum BenefitFlowEnum {
+    TOPUPS = "TOPUPS",
+    BILL_PAYMENT = "BILL_PAYMENT",
+    CREDIT = "CREDIT",
+    INSURANCE = "INSURANCE",
+    DONATION = "DONATION",
+    PHARMACY = "PHARMACY",
+    REMITTANCE = "REMITTANCE",
+    /** Fondeo de wallet PCF con efectivo via provider externo (Equality/Passport, OpenPay, …) — spec 13. */
+    WALLET_FUNDING = "WALLET_FUNDING"
+}

package/bin/benefitCenter/enums/BenefitFlowEnum.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BenefitFlowEnum = void 0;
+var BenefitFlowEnum;
+(function (BenefitFlowEnum) {
+    BenefitFlowEnum["TOPUPS"] = "TOPUPS";
+    BenefitFlowEnum["BILL_PAYMENT"] = "BILL_PAYMENT";
+    BenefitFlowEnum["CREDIT"] = "CREDIT";
+    BenefitFlowEnum["INSURANCE"] = "INSURANCE";
+    BenefitFlowEnum["DONATION"] = "DONATION";
+    BenefitFlowEnum["PHARMACY"] = "PHARMACY";
+    BenefitFlowEnum["REMITTANCE"] = "REMITTANCE";
+    /** Fondeo de wallet PCF con efectivo via provider externo (Equality/Passport, OpenPay, …) — spec 13. */
+    BenefitFlowEnum["WALLET_FUNDING"] = "WALLET_FUNDING";
+})(BenefitFlowEnum || (exports.BenefitFlowEnum = BenefitFlowEnum = {}));

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

@@ -0,0 +1,32 @@
+/**
+ * Nombre de la estación del KYC que reporta un `KycStepCompletedV1`.
+ *
+ * ⚠️ Los VALORES son exactamente las llaves de `KycSubChecks`. No es coincidencia ni estética: el
+ * consumidor arma el progreso de la verificación asentando cada estación sobre el acumulado, sin
+ * tabla de traducción. Si un valor dejara de coincidir con su llave, el progreso quedaría con un
+ * campo huérfano y la estación real nunca se marcaría — una falla muda. Ese acumulado se arma con
+ * `applyKycStep`, NO indexando a mano: la asignación directa no compila (los campos de `KycSubChecks`
+ * son opcionales) y el cast que la destraba desactiva el candado del vocabulario.
+ *
+ * Son las 8 del contrato, no las 13 que Metamap puede emitir: las otras (ip-validation, selfie,
+ * voice, duplicate-user-detection, curp/ine validation) no forman parte de `KycSubChecks` y por lo
+ * tanto no viajan. Ampliar la lista es un cambio de contrato en los dos lados, no un valor más aquí.
+ *
+ * SureKeep Fase 2 — progreso del KYC estación por estación.
+ */
+export declare enum KycSubCheckNameEnum {
+    DOCUMENT_READING = "documentReading",
+    TEMPLATE_MATCHING = "templateMatching",
+    ALTERATION_DETECTION = "alterationDetection",
+    FACEMATCH = "facematch",
+    LIVENESS = "liveness",
+    AGE_CHECK = "ageCheck",
+    WATCHLISTS = "watchlists",
+    PREMIUM_AML_WATCHLISTS = "premiumAmlWatchlists"
+}
+/**
+ * Las estaciones de LISTA — las únicas cuyo resultado se expresa en `CLEAR`/`HIT`. El resto son
+ * binarias (`PASS`/`FAIL`). Se exporta porque el validador del evento y los consumidores necesitan
+ * la MISMA partición: duplicarla en cada repo es drift garantizado.
+ */
+export declare const KYC_WATCHLIST_STEPS: readonly KycSubCheckNameEnum[];

package/bin/kyc/enums/KycSubCheckNameEnum.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KYC_WATCHLIST_STEPS = exports.KycSubCheckNameEnum = void 0;
+/**
+ * Nombre de la estación del KYC que reporta un `KycStepCompletedV1`.
+ *
+ * ⚠️ Los VALORES son exactamente las llaves de `KycSubChecks`. No es coincidencia ni estética: el
+ * consumidor arma el progreso de la verificación asentando cada estación sobre el acumulado, sin
+ * tabla de traducción. Si un valor dejara de coincidir con su llave, el progreso quedaría con un
+ * campo huérfano y la estación real nunca se marcaría — una falla muda. Ese acumulado se arma con
+ * `applyKycStep`, NO indexando a mano: la asignación directa no compila (los campos de `KycSubChecks`
+ * son opcionales) y el cast que la destraba desactiva el candado del vocabulario.
+ *
+ * Son las 8 del contrato, no las 13 que Metamap puede emitir: las otras (ip-validation, selfie,
+ * voice, duplicate-user-detection, curp/ine validation) no forman parte de `KycSubChecks` y por lo
+ * tanto no viajan. Ampliar la lista es un cambio de contrato en los dos lados, no un valor más aquí.
+ *
+ * SureKeep Fase 2 — progreso del KYC estación por estación.
+ */
+var KycSubCheckNameEnum;
+(function (KycSubCheckNameEnum) {
+    KycSubCheckNameEnum["DOCUMENT_READING"] = "documentReading";
+    KycSubCheckNameEnum["TEMPLATE_MATCHING"] = "templateMatching";
+    KycSubCheckNameEnum["ALTERATION_DETECTION"] = "alterationDetection";
+    KycSubCheckNameEnum["FACEMATCH"] = "facematch";
+    KycSubCheckNameEnum["LIVENESS"] = "liveness";
+    KycSubCheckNameEnum["AGE_CHECK"] = "ageCheck";
+    KycSubCheckNameEnum["WATCHLISTS"] = "watchlists";
+    KycSubCheckNameEnum["PREMIUM_AML_WATCHLISTS"] = "premiumAmlWatchlists";
+})(KycSubCheckNameEnum || (exports.KycSubCheckNameEnum = KycSubCheckNameEnum = {}));
+/**
+ * Las estaciones de LISTA — las únicas cuyo resultado se expresa en `CLEAR`/`HIT`. El resto son
+ * binarias (`PASS`/`FAIL`). Se exporta porque el validador del evento y los consumidores necesitan
+ * la MISMA partición: duplicarla en cada repo es drift garantizado.
+ */
+exports.KYC_WATCHLIST_STEPS = [
+    KycSubCheckNameEnum.WATCHLISTS,
+    KycSubCheckNameEnum.PREMIUM_AML_WATCHLISTS,
+];

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

@@ -0,0 +1,85 @@
+import { KycSubCheckNameEnum } from '../enums/KycSubCheckNameEnum';
+import { KycSubCheckStatusEnum } from '../enums/KycSubCheckStatusEnum';
+import { KycWatchlistStatusEnum } from '../enums/KycWatchlistStatusEnum';
+/**
+ * El resultado de UNA estación del KYC, publicado por `kyc-metamap-webhook` en cuanto Metamap la
+ * cierra (`step_completed`) — no al final de la verificación.
+ *
+ * **Por qué existe:** `KycVerificationChangedV1` llega UNA vez, cuando todo terminó. Con eso la
+ * pantalla del vendedor solo puede mostrar una ruedita hasta el veredicto. Metamap emite un webhook
+ * por estación y el webhook ya los recibía; lo único que faltaba era reenviarlos. Este evento es ese
+ * reenvío: deja que SureKeep pinte el avance estación por estación mientras el cliente espera.
+ *
+ * **Convive con `KycVerificationChangedV1` en la MISMA cola** (`RetailKycInboundQueue`). El
+ * discriminador es la presencia de `step`: si lo trae, es una estación; si no, es el cierre. Por eso
+ * `KycVerificationChangedV1` no se tocó — un consumidor viejo que no conoce este evento lo descarta
+ * en su propio parseo sin romperse.
+ *
+ * 🔴 **NO es un veredicto.** Un `FAIL` acá no rechaza nada ni frena la venta: el cliente reintenta
+ * dentro del mismo SDK, en el mismo dispositivo, sin salir de la sesión. La decisión sigue viniendo
+ * del estado consolidado (`RetailKycStatusEnum`) que llega en el cierre. Esto es progreso visible,
+ * no política.
+ *
+ * 🔴 **Sin PII, a propósito.** No lleva `person`, ni `address`, ni `peopleId`: una estación solo
+ * necesita decir cuál es y cómo salió. Lo que sí lleva son identificadores operacionales, que es lo
+ * único que se puede loguear.
+ *
+ * **Idempotencia:** la clave es `(verificationId, step)` — NO viaja `eventId` a propósito. Una
+ * estación cierra una sola vez por verificación, y asentar su resultado sobre el progreso
+ * (`applyKycStep`) es idempotente por diseño: reprocesar el mismo evento escribe el mismo valor. Que
+ * quede dicho acá y no en la cabeza de cada consumidor: deducirlo mal lleva a deduplicar por el
+ * `MessageId` de SQS, que cambia en cada reintento de entrega y por lo tanto no deduplica nada.
+ *
+ * SureKeep Fase 2 — progreso del KYC estación por estación.
+ */
+export declare class KycStepCompletedV1 {
+    /**
+     * Discriminador EXPLÍCITO del tipo de evento. Opcional hoy, y esa es toda la gracia: agregarlo
+     * ahora es gratis; agregarlo después de que el webhook publique en Dev ya sería breaking.
+     *
+     * Sin él, el ruteo del consumidor depende de la presencia de `step`. Eso funciona con los dos
+     * eventos de hoy, pero Metamap también emite `step_started`: el día que alguien publique un
+     * `KycStepStartedV1` traería `step` sin `status`, el consumidor lo rutearía a esta rama y el
+     * mensaje caería al DLQ etiquetado como "corrupto" en vez de "no soportado" — se diagnostica
+     * como bug del webhook cuando en realidad es un evento nuevo legítimo.
+     *
+     * Regla de ruteo hacia adelante: si `eventType` viene y matchea → esta rama; si no viene
+     * ninguno → el cierre legacy (`KycVerificationChangedV1`).
+     */
+    eventType?: string;
+    /** Correlaciona la estación con su verificación. */
+    verificationId: string;
+    /**
+     * Con esto el consumidor encuentra la sesión (el gate de pertenencia). DEC-KYC-015: `@IsNotEmpty()`
+     * y no solo `@IsString()` — un `''` colado dejaría el gate sin nada contra qué buscar y el evento
+     * fallaría tres pasos río abajo en vez de en el boundary.
+     */
+    directoryId: string;
+    /** Cuál estación cerró. El valor coincide con su llave en `KycSubChecks`. */
+    step: KycSubCheckNameEnum;
+    /**
+     * Cómo salió, en el vocabulario de SU estación: `CLEAR`/`HIT` en las de lista, `PASS`/`FAIL` en
+     * las binarias. El cruce lo valida `IsKycStepStatusByStep` — un `@IsIn` con los cuatro valores
+     * aceptaría `watchlists: FAIL` y perdería el matiz de que un HIT no es un fallo.
+     */
+    status: KycSubCheckStatusEnum | KycWatchlistStatusEnum;
+    /**
+     * Cuándo cerró la estación, según Metamap. **Obligatorio, y no es decorativo:** la cola es SQS
+     * estándar, que no garantiza orden. Sin una marca de tiempo por evento, una estación reordenada
+     * puede pisar el cierre de la verificación y "des-cerrar" la lista ya completa en pantalla. El
+     * consumidor descarta las que llegan más viejas que lo que ya escribió.
+     *
+     * ⚠️ **UTC estricto, con `Z` y sin offset** — por eso el `@Matches` además del `@IsISO8601()`.
+     * `@IsISO8601()` solo NO alcanza: acepta `2026-07-26` (sin hora), `2026-W30-1` (fecha de semana)
+     * y, sobre todo, `2026-07-26T15:05:00+05:00`. Ese último es el que hace daño. Si una estación
+     * llega con offset `+05:00` y la siguiente en `Z`, la comparación léxica que hace el consumidor
+     * concluye que la más nueva es más vieja y la DESCARTA: la estación nunca se pinta y nada truena.
+     *
+     * Normalizar a UTC es trabajo del webhook — es el traductor del proveedor, y este candado existe
+     * para que si algún día deja de hacerlo, el evento caiga al DLQ en el boundary en vez de
+     * corromper el orden en silencio.
+     */
+    occurredAt: string;
+    /** El flujo de Metamap que corrió. Solo para diagnóstico — nadie ramifica por él. */
+    metamapFlowId?: string;
+}