@fiado/type-kit 3.302.0 → 3.303.0

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

@@ -0,0 +1,195 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import {
+  KycProofOfAddressCompletedV1,
+  KycStepCompletedV1,
+  ProofAddressStatusEnum,
+} from '../../../src/kyc/index';
+
+/** Base válida del evento; cada caso pisa solo el campo que está probando. */
+const base = {
+  eventType: 'KycProofOfAddressCompletedV1',
+  verificationId: 'ver-1',
+  directoryId: 'dir-1',
+  peopleId: 'ppl-1',
+  status: 'SUCCESS',
+  addressPersisted: true,
+  occurredAt: '2026-08-11T10:05:00.000Z',
+};
+
+const instancia = (raw: Record<string, unknown>): KycProofOfAddressCompletedV1 =>
+  plainToInstance(KycProofOfAddressCompletedV1, raw, { excludeExtraneousValues: true });
+
+describe('KycProofOfAddressCompletedV1', () => {
+  it('valida el shape que publica el webhook al cerrar el comprobante', async () => {
+    const dto = instancia(base);
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.status).toBe(ProofAddressStatusEnum.SUCCESS);
+    expect(dto.addressPersisted).toBe(true);
+  });
+
+  it('valida con peopleId vacío (Metamap no siempre lo manda)', async () => {
+    const dto = instancia({ ...base, peopleId: '' });
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.peopleId).toBe('');
+  });
+
+  it('valida sin peopleId', async () => {
+    const { peopleId: _omitido, ...sinPeople } = base;
+
+    expect(await validate(instancia(sinPeople) as object)).toHaveLength(0);
+  });
+
+  // ── eventType: acá SÍ es obligatorio ──────────────────────────────────────
+
+  /**
+   * A diferencia de `KycStepCompletedV1`, donde es opcional por los mensajes que ya estaban en
+   * vuelo. Este evento nace hoy: el discriminador puede exigirse desde el primer mensaje.
+   */
+  it('rechaza un evento sin eventType (el discriminador es obligatorio)', async () => {
+    const { eventType: _omitido, ...sinTipo } = base;
+    const errors = await validate(instancia(sinTipo) as object);
+
+    expect(errors.map((e) => e.property)).toContain('eventType');
+  });
+
+  it('rechaza un eventType de otro evento', async () => {
+    const errors = await validate(instancia({ ...base, eventType: 'KycStepCompletedV1' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('eventType');
+  });
+
+  // ── Identificadores ───────────────────────────────────────────────────────
+
+  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);
+  });
+
+  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');
+  });
+
+  // ── status y addressPersisted ─────────────────────────────────────────────
+
+  it.each(Object.values(ProofAddressStatusEnum))('acepta el status %s', async (status) => {
+    expect(await validate(instancia({ ...base, status }) as object)).toHaveLength(0);
+  });
+
+  it('rechaza un status fuera del enum', async () => {
+    const errors = await validate(instancia({ ...base, status: 'MAS_O_MENOS' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('status');
+  });
+
+  /**
+   * Va explícito aunque sea derivable del `status`: sin él cada consumidor reimplementaría el mapa
+   * de 12 casos, y ese mapa lo conoce el productor.
+   */
+  it('rechaza un evento sin addressPersisted', async () => {
+    const { addressPersisted: _omitido, ...sinFlag } = base;
+    const errors = await validate(instancia(sinFlag) as object);
+
+    expect(errors.map((e) => e.property)).toContain('addressPersisted');
+  });
+
+  it('rechaza addressPersisted que no sea booleano', async () => {
+    const errors = await validate(instancia({ ...base, addressPersisted: 'true' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('addressPersisted');
+  });
+
+  it('acepta el caso sin domicilio guardado', async () => {
+    const dto = instancia({
+      ...base,
+      status: ProofAddressStatusEnum.NO_ADDRESS_DETECTED,
+      addressPersisted: false,
+    });
+
+    expect(await validate(dto as object)).toHaveLength(0);
+    expect(dto.addressPersisted).toBe(false);
+  });
+
+  // ── Orden ─────────────────────────────────────────────────────────────────
+
+  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. El offset es el que hace daño: rompe la comparación
+   * léxica del consumidor, que descarta el evento real sin que nada truene.
+   */
+  it.each([
+    ['offset positivo en vez de Z', '2026-08-11T15:05:00+05:00'],
+    ['offset negativo en vez de Z', '2026-08-11T05:05:00-05:00'],
+    ['solo fecha, sin hora', '2026-08-11'],
+    ['formato básico sin guiones', '20260811T100500Z'],
+    ['fecha de semana ISO', '2026-W30-1'],
+    ['fecha imposible', '2026-02-30T10:05:00.000Z'],
+    ['sin zona horaria', '2026-08-11T10: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-08-11T10:05:00.000Z'],
+    ['sin milisegundos', '2026-08-11T10:05:00Z'],
+  ])('acepta occurredAt en UTC %s', async (_etiqueta, valor) => {
+    expect(await validate(instancia({ ...base, occurredAt: valor }) as object)).toHaveLength(0);
+  });
+
+  // ── Convivencia en RetailKycInboundQueue ──────────────────────────────────
+
+  /**
+   * Los tres eventos comparten cola. Estos candados prueban que uno no se puede hacer pasar por
+   * otro: si se volvieran mutuamente válidos, el consumidor tomaría la rama equivocada.
+   */
+  it('un cierre de estación NO valida como comprobante de domicilio', async () => {
+    const estacion = {
+      eventType: 'KycStepCompletedV1', verificationId: 'ver-1', directoryId: 'dir-1',
+      step: 'facematch', status: 'PASS', occurredAt: '2026-08-11T10:05:00.000Z',
+    };
+
+    const errors = await validate(instancia(estacion) as object);
+
+    expect(errors.map((e) => e.property)).toEqual(
+      expect.arrayContaining(['eventType', 'status', 'addressPersisted']),
+    );
+  });
+
+  it('un comprobante de domicilio NO valida como cierre de estación', async () => {
+    const dto = plainToInstance(KycStepCompletedV1, base, { excludeExtraneousValues: true });
+    const errors = await validate(dto as object);
+
+    expect(errors.map((e) => e.property)).toEqual(expect.arrayContaining(['eventType', 'step', 'status']));
+  });
+
+  // ── El espejo con fiado-abstractions ──────────────────────────────────────
+
+  /**
+   * El enum se espeja de `@fiado/fiado-abstractions` porque el wizard no depende de esa lib. Si allá
+   * agregan un caso y acá no, el evento con ese status caería al DLQ como corrupto.
+   */
+  it('declara los 12 estados del comprobante', () => {
+    expect(Object.values(ProofAddressStatusEnum).sort()).toEqual(
+      [
+        'SUCCESS', 'MEX_HELP_NEEDED', 'USA_HELP_NEEDED', 'COUNTRY_MISMATCH',
+        'COUNTRY_NOT_SUPPORTED', 'PENDING_METAMAP_REVIEW', 'NO_ADDRESS_DETECTED',
+        'PLACES_NO_MATCH', 'METAMAP_ERROR', 'PLACES_ERROR', 'ADDRESS_SAVE_ERROR', 'CHECKBOX_ERROR',
+      ].sort(),
+    );
+  });
+});

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

@@ -0,0 +1,26 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validate } from 'class-validator';
+import { ProofOfAddressPrepareRequest } from '../../../src/retailWizard/index';
+
+const instancia = (raw: Record<string, unknown>): ProofOfAddressPrepareRequest =>
+  plainToInstance(ProofOfAddressPrepareRequest, raw, { excludeExtraneousValues: true });
+
+describe('ProofOfAddressPrepareRequest', () => {
+  it.each(['CUSTOMER_LINK', 'STORE_DEVICE'])('acepta la modalidad %s', async (modality) => {
+    expect(await validate(instancia({ modality }) as object)).toHaveLength(0);
+  });
+
+  it('rechaza un request sin modality', async () => {
+    const errors = await validate(instancia({}) as object);
+
+    expect(errors.map((e) => e.property)).toContain('modality');
+  });
+
+  // MANUAL no es una modalidad de prepare: la captura manual es su propio endpoint.
+  it('rechaza MANUAL', async () => {
+    const errors = await validate(instancia({ modality: 'MANUAL' }) as object);
+
+    expect(errors.map((e) => e.property)).toContain('modality');
+  });
+});

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

@@ -0,0 +1,33 @@
+/**
+ * Resultado del procesamiento del comprobante de domicilio de Metamap: "¿pudimos usar el
+ * comprobante?", que no es lo mismo que "¿Metamap aprobó el documento?".
+ *
+ * Espeja `@fiado/fiado-abstractions` (`Fiado/Identity/ProofAddressStatusEnum`) porque los
+ * consumidores de SureKeep no dependen de esa lib.
+ */
+export declare enum ProofAddressStatusEnum {
+    /** Domicilio de México o Estados Unidos resuelto a nivel calle y guardado con sus componentes. */
+    SUCCESS = "SUCCESS",
+    /** Domicilio mexicano que el geocoder no resolvió a nivel calle. Se guardó el texto del recibo para revisión manual. */
+    MEX_HELP_NEEDED = "MEX_HELP_NEEDED",
+    /** Igual que `MEX_HELP_NEEDED`, para un domicilio estadounidense. */
+    USA_HELP_NEEDED = "USA_HELP_NEEDED",
+    /** El usuario declaró un país en Metamap y el domicilio resolvió al otro. Requiere revisión. */
+    COUNTRY_MISMATCH = "COUNTRY_MISMATCH",
+    /** El domicilio es de un país fuera de México y Estados Unidos. Se guarda pero NO habilita el requisito. */
+    COUNTRY_NOT_SUPPORTED = "COUNTRY_NOT_SUPPORTED",
+    /** Metamap mandó el documento a revisión manual. No se procesa hasta tener su veredicto. */
+    PENDING_METAMAP_REVIEW = "PENDING_METAMAP_REVIEW",
+    /** El OCR de Metamap no devolvió domicilio: el comprobante es ilegible o no es un comprobante. */
+    NO_ADDRESS_DETECTED = "NO_ADDRESS_DETECTED",
+    /** El geocoder respondió sin candidatos. Texto ilegible o domicilio fuera de los países consultados. */
+    PLACES_NO_MATCH = "PLACES_NO_MATCH",
+    /** No se pudo traer la evidencia de Metamap (timeout, 5xx). Reintentable. */
+    METAMAP_ERROR = "METAMAP_ERROR",
+    /** Falló `places-business`. Reintentable. */
+    PLACES_ERROR = "PLACES_ERROR",
+    /** Falló `fiado-address-lambda` al guardar el domicilio. Reintentable. */
+    ADDRESS_SAVE_ERROR = "ADDRESS_SAVE_ERROR",
+    /** El domicilio se guardó pero falló prender la casilla. Reintentable — el dato está a salvo. */
+    CHECKBOX_ERROR = "CHECKBOX_ERROR"
+}

package/bin/kyc/enums/ProofAddressStatusEnum.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProofAddressStatusEnum = void 0;
+/**
+ * Resultado del procesamiento del comprobante de domicilio de Metamap: "¿pudimos usar el
+ * comprobante?", que no es lo mismo que "¿Metamap aprobó el documento?".
+ *
+ * Espeja `@fiado/fiado-abstractions` (`Fiado/Identity/ProofAddressStatusEnum`) porque los
+ * consumidores de SureKeep no dependen de esa lib.
+ */
+var ProofAddressStatusEnum;
+(function (ProofAddressStatusEnum) {
+    /** Domicilio de México o Estados Unidos resuelto a nivel calle y guardado con sus componentes. */
+    ProofAddressStatusEnum["SUCCESS"] = "SUCCESS";
+    /** Domicilio mexicano que el geocoder no resolvió a nivel calle. Se guardó el texto del recibo para revisión manual. */
+    ProofAddressStatusEnum["MEX_HELP_NEEDED"] = "MEX_HELP_NEEDED";
+    /** Igual que `MEX_HELP_NEEDED`, para un domicilio estadounidense. */
+    ProofAddressStatusEnum["USA_HELP_NEEDED"] = "USA_HELP_NEEDED";
+    /** El usuario declaró un país en Metamap y el domicilio resolvió al otro. Requiere revisión. */
+    ProofAddressStatusEnum["COUNTRY_MISMATCH"] = "COUNTRY_MISMATCH";
+    /** El domicilio es de un país fuera de México y Estados Unidos. Se guarda pero NO habilita el requisito. */
+    ProofAddressStatusEnum["COUNTRY_NOT_SUPPORTED"] = "COUNTRY_NOT_SUPPORTED";
+    /** Metamap mandó el documento a revisión manual. No se procesa hasta tener su veredicto. */
+    ProofAddressStatusEnum["PENDING_METAMAP_REVIEW"] = "PENDING_METAMAP_REVIEW";
+    /** El OCR de Metamap no devolvió domicilio: el comprobante es ilegible o no es un comprobante. */
+    ProofAddressStatusEnum["NO_ADDRESS_DETECTED"] = "NO_ADDRESS_DETECTED";
+    /** El geocoder respondió sin candidatos. Texto ilegible o domicilio fuera de los países consultados. */
+    ProofAddressStatusEnum["PLACES_NO_MATCH"] = "PLACES_NO_MATCH";
+    /** No se pudo traer la evidencia de Metamap (timeout, 5xx). Reintentable. */
+    ProofAddressStatusEnum["METAMAP_ERROR"] = "METAMAP_ERROR";
+    /** Falló `places-business`. Reintentable. */
+    ProofAddressStatusEnum["PLACES_ERROR"] = "PLACES_ERROR";
+    /** Falló `fiado-address-lambda` al guardar el domicilio. Reintentable. */
+    ProofAddressStatusEnum["ADDRESS_SAVE_ERROR"] = "ADDRESS_SAVE_ERROR";
+    /** El domicilio se guardó pero falló prender la casilla. Reintentable — el dato está a salvo. */
+    ProofAddressStatusEnum["CHECKBOX_ERROR"] = "CHECKBOX_ERROR";
+})(ProofAddressStatusEnum || (exports.ProofAddressStatusEnum = ProofAddressStatusEnum = {}));

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

@@ -0,0 +1,49 @@
+import { ProofAddressStatusEnum } from '../enums/ProofAddressStatusEnum';
+/**
+ * El resultado del COMPROBANTE DE DOMICILIO de Metamap, publicado por `kyc-metamap-webhook` cuando
+ * termina de procesarlo. Es un flow aparte del documento de identidad.
+ *
+ * **Convive con `KycVerificationChangedV1` y `KycStepCompletedV1` en la MISMA cola**
+ * (`RetailKycInboundQueue`). El discriminador es `eventType`.
+ *
+ * 🔴 **Sin PII, a propósito.** No lleva el domicilio ni el texto del recibo: solo identificadores
+ * operacionales y el veredicto. Quien necesite el domicilio lo lee del expediente del cliente.
+ *
+ * **Idempotencia:** la clave es `verificationId`. Un comprobante se procesa una sola vez por
+ * verificación; reprocesar el evento escribe el mismo valor.
+ *
+ * SureKeep Fase 2 — comprobante de domicilio del paso 02.
+ */
+export declare class KycProofOfAddressCompletedV1 {
+    /**
+     * Discriminador del tipo de evento. **Requerido**, a diferencia de `KycStepCompletedV1`: ese es
+     * opcional por los mensajes que ya estaban en vuelo, éste nace hoy y puede exigirlo desde el primero.
+     */
+    eventType: string;
+    /** Correlaciona el comprobante con su verificación de Metamap. */
+    verificationId: string;
+    /**
+     * Con esto el consumidor encuentra la sesión (el gate de pertenencia). `@IsNotEmpty()` y no solo
+     * `@IsString()`: un `''` colado fallaría tres pasos río abajo en vez de en el boundary.
+     */
+    directoryId: string;
+    /** Identidad Fiado del cliente. Opcional: el productor publica `''` cuando Metamap no lo manda. */
+    peopleId?: string;
+    /** Por qué el comprobante quedó como quedó — el motivo legible, no solo si sirvió. */
+    status: ProofAddressStatusEnum;
+    /**
+     * ¿Quedó un domicilio en el expediente del cliente? Va explícito aunque sea derivable del
+     * `status`: sin él cada consumidor reimplementaría el mapa de 12 casos que conoce el productor.
+     */
+    addressPersisted: boolean;
+    /**
+     * Cuándo se cerró el comprobante. **Obligatorio:** la cola es SQS estándar, que no garantiza
+     * orden, y el consumidor descarta lo que llega más viejo que lo que ya escribió.
+     *
+     * ⚠️ **UTC estricto, con `Z` y sin offset** — por eso el `@Matches` además del `@IsISO8601()`.
+     * `@IsISO8601()` solo acepta `2026-08-11T15:05:00+05:00`, y ese es el que hace daño: léxicamente
+     * es "mayor" que un `T10:06:00Z` posterior, así que el consumidor descarta el evento real y nada
+     * truena. Normalizar a UTC es trabajo del webhook; este candado lo manda al DLQ si deja de hacerlo.
+     */
+    occurredAt: string;
+}

package/bin/kyc/events/KycProofOfAddressCompletedV1.js

@@ -0,0 +1,75 @@
+"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.KycProofOfAddressCompletedV1 = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const ProofAddressStatusEnum_1 = require("../enums/ProofAddressStatusEnum");
+/**
+ * El resultado del COMPROBANTE DE DOMICILIO de Metamap, publicado por `kyc-metamap-webhook` cuando
+ * termina de procesarlo. Es un flow aparte del documento de identidad.
+ *
+ * **Convive con `KycVerificationChangedV1` y `KycStepCompletedV1` en la MISMA cola**
+ * (`RetailKycInboundQueue`). El discriminador es `eventType`.
+ *
+ * 🔴 **Sin PII, a propósito.** No lleva el domicilio ni el texto del recibo: solo identificadores
+ * operacionales y el veredicto. Quien necesite el domicilio lo lee del expediente del cliente.
+ *
+ * **Idempotencia:** la clave es `verificationId`. Un comprobante se procesa una sola vez por
+ * verificación; reprocesar el evento escribe el mismo valor.
+ *
+ * SureKeep Fase 2 — comprobante de domicilio del paso 02.
+ */
+class KycProofOfAddressCompletedV1 {
+}
+exports.KycProofOfAddressCompletedV1 = KycProofOfAddressCompletedV1;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsIn)(['KycProofOfAddressCompletedV1']),
+    __metadata("design:type", String)
+], KycProofOfAddressCompletedV1.prototype, "eventType", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], KycProofOfAddressCompletedV1.prototype, "verificationId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], KycProofOfAddressCompletedV1.prototype, "directoryId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsString)(),
+    __metadata("design:type", String)
+], KycProofOfAddressCompletedV1.prototype, "peopleId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsEnum)(ProofAddressStatusEnum_1.ProofAddressStatusEnum),
+    __metadata("design:type", String)
+], KycProofOfAddressCompletedV1.prototype, "status", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], KycProofOfAddressCompletedV1.prototype, "addressPersisted", 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-08-11T10:05:00.000Z): un offset rompe el orden léxico',
+    }),
+    __metadata("design:type", String)
+], KycProofOfAddressCompletedV1.prototype, "occurredAt", void 0);

package/bin/kyc/index.d.ts

@@ -2,6 +2,7 @@ export * from './enums/KycVerificationStatusEnum';
 export * from './enums/KycSubCheckStatusEnum';
 export * from './enums/KycWatchlistStatusEnum';
 export * from './enums/KycSubCheckNameEnum';
+export * from './enums/ProofAddressStatusEnum';
 export * from './dtos/KycSubChecks';
 export * from './validators/IsKycStepStatusByStep';
 export * from './helpers/applyKycStep';
@@ -10,3 +11,4 @@ export * from './dtos/responses/KycPersonData';
 export * from './dtos/responses/KycByDirectoryResponse';
 export * from './events/KycVerificationChangedV1';
 export * from './events/KycStepCompletedV1';
+export * from './events/KycProofOfAddressCompletedV1';

package/bin/kyc/index.js

@@ -20,6 +20,7 @@ __exportStar(require("./enums/KycVerificationStatusEnum"), exports);
 __exportStar(require("./enums/KycSubCheckStatusEnum"), exports);
 __exportStar(require("./enums/KycWatchlistStatusEnum"), exports);
 __exportStar(require("./enums/KycSubCheckNameEnum"), exports);
+__exportStar(require("./enums/ProofAddressStatusEnum"), exports);
 // Sub-pasos descompuestos (SureKeep F2)
 __exportStar(require("./dtos/KycSubChecks"), exports);
 // Validators
@@ -34,3 +35,4 @@ __exportStar(require("./dtos/responses/KycByDirectoryResponse"), exports);
 // Events
 __exportStar(require("./events/KycVerificationChangedV1"), exports);
 __exportStar(require("./events/KycStepCompletedV1"), exports);
+__exportStar(require("./events/KycProofOfAddressCompletedV1"), exports);

package/bin/retailWizard/dtos/requests/ProofOfAddressPrepareRequest.d.ts

@@ -0,0 +1,10 @@
+import { KycModalityInput } from './KycPrepareRequest';
+/**
+ * POST /wizard/sessions/:id/proof-of-address/prepare — prepara el flujo del COMPROBANTE DE
+ * DOMICILIO de Metamap. Gemelo de `KycPrepareRequest` para el otro flow.
+ * `modality` = link al cliente o captura en tablet.
+ * SureKeep Fase 2 — pista Retail.
+ */
+export declare class ProofOfAddressPrepareRequest {
+    modality: KycModalityInput;
+}

package/bin/retailWizard/dtos/requests/ProofOfAddressPrepareRequest.js

@@ -0,0 +1,28 @@
+"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.ProofOfAddressPrepareRequest = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/**
+ * POST /wizard/sessions/:id/proof-of-address/prepare — prepara el flujo del COMPROBANTE DE
+ * DOMICILIO de Metamap. Gemelo de `KycPrepareRequest` para el otro flow.
+ * `modality` = link al cliente o captura en tablet.
+ * SureKeep Fase 2 — pista Retail.
+ */
+class ProofOfAddressPrepareRequest {
+}
+exports.ProofOfAddressPrepareRequest = ProofOfAddressPrepareRequest;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsIn)(['CUSTOMER_LINK', 'STORE_DEVICE']),
+    __metadata("design:type", String)
+], ProofOfAddressPrepareRequest.prototype, "modality", void 0);

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

@@ -47,6 +47,21 @@ export interface KycSdkMetadata {
      * no código.
      */
     source?: KycMetadataSourceEnum;
+    /**
+     * Paso del onboarding que originó la verificación. Es lo único que distingue al comprobante de
+     * domicilio del documento de identidad: `kyc-metamap-webhook` rutea por este campo.
+     */
+    kycStep?: KycMetadataStepEnum;
+}
+/**
+ * Paso del onboarding que originó una verificación, tal como viaja en `KycSdkMetadata.kycStep`.
+ *
+ * Enum y no string libre por el mismo motivo que `KycMetadataSourceEnum`: el valor lo escribe un
+ * repo (`retail-wizard-business`) y lo compara otro (`kyc-metamap-webhook`). Un typo dejaría al
+ * webhook procesando el comprobante como si fuera un documento de identidad, sin un solo error.
+ */
+export declare enum KycMetadataStepEnum {
+    PROOF_OF_ADDRESS = "PROOF_OF_ADDRESS"
 }
 /**
  * Producto que originó una verificación KYC, tal como viaja en `KycSdkMetadata.source`.

package/bin/retailWizard/dtos/responses/KycPrepareResponse.js

@@ -1,6 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KycMetadataSourceEnum = void 0;
+exports.KycMetadataSourceEnum = exports.KycMetadataStepEnum = void 0;
+/**
+ * Paso del onboarding que originó una verificación, tal como viaja en `KycSdkMetadata.kycStep`.
+ *
+ * Enum y no string libre por el mismo motivo que `KycMetadataSourceEnum`: el valor lo escribe un
+ * repo (`retail-wizard-business`) y lo compara otro (`kyc-metamap-webhook`). Un typo dejaría al
+ * webhook procesando el comprobante como si fuera un documento de identidad, sin un solo error.
+ */
+var KycMetadataStepEnum;
+(function (KycMetadataStepEnum) {
+    KycMetadataStepEnum["PROOF_OF_ADDRESS"] = "PROOF_OF_ADDRESS";
+})(KycMetadataStepEnum || (exports.KycMetadataStepEnum = KycMetadataStepEnum = {}));
 /**
  * Producto que originó una verificación KYC, tal como viaja en `KycSdkMetadata.source`.
  *

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

@@ -0,0 +1,26 @@
+import { KycModalityEnum } from '../../../retailCustomer/enums/KycModalityEnum';
+/**
+ * POST /wizard/sessions/:id/proof-of-address/prepare — respuesta. Gemelo de `KycPrepareResponse`
+ * para el flow del comprobante de domicilio; la metadata del SDK es la misma `KycSdkMetadata` y la
+ * marca de que es comprobante viaja en su `kycStep`.
+ *
+ * **Bifurca por modalidad**, por eso todo es opcional salvo `modality`:
+ * - `STORE_DEVICE` → `clientId` + `flowId` + `metadata` para montar el `<metamap-button>` en la tablet.
+ * - `CUSTOMER_LINK` → `shortUrl` para el QR / SMS al teléfono del cliente.
+ *
+ * SureKeep Fase 2 — pista Retail.
+ */
+export interface ProofOfAddressPrepareResponse {
+    /** `MANUAL` no es una modalidad de `prepare`: la captura manual es su propio endpoint. */
+    modality: KycModalityEnum.CUSTOMER_LINK | KycModalityEnum.STORE_DEVICE;
+    /** STORE_DEVICE — clientId de la cuenta Metamap (mismo valor en prod y dev). */
+    clientId?: string;
+    /** STORE_DEVICE — flow de Metamap del comprobante de domicilio. */
+    flowId?: string;
+    /** STORE_DEVICE — `KycSdkMetadata` serializada en base64. */
+    metadata?: string;
+    /** CUSTOMER_LINK — link corto para el QR o el SMS. */
+    shortUrl?: string;
+    /** El expediente ya tiene domicilio principal: no hay comprobante que pedir. */
+    alreadyHasAddress?: boolean;
+}

package/bin/retailWizard/dtos/responses/ProofOfAddressPrepareResponse.js

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

package/bin/retailWizard/index.d.ts

@@ -40,6 +40,7 @@ export * from './dtos/requests/ConsentsRequest';
 export * from './dtos/requests/KycPrepareRequest';
 export * from './dtos/requests/KycConfirmRequest';
 export * from './dtos/requests/KycManualRequest';
+export * from './dtos/requests/ProofOfAddressPrepareRequest';
 export * from './dtos/requests/OccupationRequest';
 export * from './dtos/requests/AddProductRequest';
 export * from './dtos/requests/DeleteProductRequest';
@@ -63,6 +64,7 @@ export * from './dtos/requests/DownPaymentRequest';
 export * from './dtos/requests/SignatureSignRequest';
 export * from './dtos/requests/RegisterDeviceRequest';
 export * from './dtos/responses/KycPrepareResponse';
+export * from './dtos/responses/ProofOfAddressPrepareResponse';
 export * from './dtos/responses/SessionFinanciersResponse';
 export * from './dtos/responses/ScoreConsultResponse';
 export * from './dtos/responses/ScoreResultResponse';

package/bin/retailWizard/index.js

@@ -62,6 +62,7 @@ __exportStar(require("./dtos/requests/ConsentsRequest"), exports);
 __exportStar(require("./dtos/requests/KycPrepareRequest"), exports);
 __exportStar(require("./dtos/requests/KycConfirmRequest"), exports);
 __exportStar(require("./dtos/requests/KycManualRequest"), exports);
+__exportStar(require("./dtos/requests/ProofOfAddressPrepareRequest"), exports);
 __exportStar(require("./dtos/requests/OccupationRequest"), exports);
 __exportStar(require("./dtos/requests/AddProductRequest"), exports);
 __exportStar(require("./dtos/requests/DeleteProductRequest"), exports);
@@ -86,6 +87,7 @@ __exportStar(require("./dtos/requests/SignatureSignRequest"), exports);
 __exportStar(require("./dtos/requests/RegisterDeviceRequest"), exports);
 // Response DTOs (output tipado por endpoint)
 __exportStar(require("./dtos/responses/KycPrepareResponse"), exports);
+__exportStar(require("./dtos/responses/ProofOfAddressPrepareResponse"), exports);
 __exportStar(require("./dtos/responses/SessionFinanciersResponse"), exports);
 __exportStar(require("./dtos/responses/ScoreConsultResponse"), exports);
 __exportStar(require("./dtos/responses/ScoreResultResponse"), exports);

package/package.json

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

package/src/kyc/enums/ProofAddressStatusEnum.ts

@@ -0,0 +1,44 @@
+/**
+ * Resultado del procesamiento del comprobante de domicilio de Metamap: "¿pudimos usar el
+ * comprobante?", que no es lo mismo que "¿Metamap aprobó el documento?".
+ *
+ * Espeja `@fiado/fiado-abstractions` (`Fiado/Identity/ProofAddressStatusEnum`) porque los
+ * consumidores de SureKeep no dependen de esa lib.
+ */
+export enum ProofAddressStatusEnum {
+    /** Domicilio de México o Estados Unidos resuelto a nivel calle y guardado con sus componentes. */
+    SUCCESS = "SUCCESS",
+
+    /** Domicilio mexicano que el geocoder no resolvió a nivel calle. Se guardó el texto del recibo para revisión manual. */
+    MEX_HELP_NEEDED = "MEX_HELP_NEEDED",
+
+    /** Igual que `MEX_HELP_NEEDED`, para un domicilio estadounidense. */
+    USA_HELP_NEEDED = "USA_HELP_NEEDED",
+
+    /** El usuario declaró un país en Metamap y el domicilio resolvió al otro. Requiere revisión. */
+    COUNTRY_MISMATCH = "COUNTRY_MISMATCH",
+
+    /** El domicilio es de un país fuera de México y Estados Unidos. Se guarda pero NO habilita el requisito. */
+    COUNTRY_NOT_SUPPORTED = "COUNTRY_NOT_SUPPORTED",
+
+    /** Metamap mandó el documento a revisión manual. No se procesa hasta tener su veredicto. */
+    PENDING_METAMAP_REVIEW = "PENDING_METAMAP_REVIEW",
+
+    /** El OCR de Metamap no devolvió domicilio: el comprobante es ilegible o no es un comprobante. */
+    NO_ADDRESS_DETECTED = "NO_ADDRESS_DETECTED",
+
+    /** El geocoder respondió sin candidatos. Texto ilegible o domicilio fuera de los países consultados. */
+    PLACES_NO_MATCH = "PLACES_NO_MATCH",
+
+    /** No se pudo traer la evidencia de Metamap (timeout, 5xx). Reintentable. */
+    METAMAP_ERROR = "METAMAP_ERROR",
+
+    /** Falló `places-business`. Reintentable. */
+    PLACES_ERROR = "PLACES_ERROR",
+
+    /** Falló `fiado-address-lambda` al guardar el domicilio. Reintentable. */
+    ADDRESS_SAVE_ERROR = "ADDRESS_SAVE_ERROR",
+
+    /** El domicilio se guardó pero falló prender la casilla. Reintentable — el dato está a salvo. */
+    CHECKBOX_ERROR = "CHECKBOX_ERROR",
+}

package/src/kyc/events/KycProofOfAddressCompletedV1.ts

@@ -0,0 +1,68 @@
+import { Expose } from 'class-transformer';
+import { IsBoolean, IsEnum, IsIn, IsISO8601, IsNotEmpty, IsOptional, IsString, Matches } from 'class-validator';
+import { ProofAddressStatusEnum } from '../enums/ProofAddressStatusEnum';
+
+/**
+ * El resultado del COMPROBANTE DE DOMICILIO de Metamap, publicado por `kyc-metamap-webhook` cuando
+ * termina de procesarlo. Es un flow aparte del documento de identidad.
+ *
+ * **Convive con `KycVerificationChangedV1` y `KycStepCompletedV1` en la MISMA cola**
+ * (`RetailKycInboundQueue`). El discriminador es `eventType`.
+ *
+ * 🔴 **Sin PII, a propósito.** No lleva el domicilio ni el texto del recibo: solo identificadores
+ * operacionales y el veredicto. Quien necesite el domicilio lo lee del expediente del cliente.
+ *
+ * **Idempotencia:** la clave es `verificationId`. Un comprobante se procesa una sola vez por
+ * verificación; reprocesar el evento escribe el mismo valor.
+ *
+ * SureKeep Fase 2 — comprobante de domicilio del paso 02.
+ */
+export class KycProofOfAddressCompletedV1 {
+    /**
+     * Discriminador del tipo de evento. **Requerido**, a diferencia de `KycStepCompletedV1`: ese es
+     * opcional por los mensajes que ya estaban en vuelo, éste nace hoy y puede exigirlo desde el primero.
+     */
+    @Expose() @IsIn(['KycProofOfAddressCompletedV1'])
+    eventType!: string;
+
+    /** Correlaciona el comprobante con su verificación de Metamap. */
+    @Expose() @IsString() @IsNotEmpty()
+    verificationId!: string;
+
+    /**
+     * Con esto el consumidor encuentra la sesión (el gate de pertenencia). `@IsNotEmpty()` y no solo
+     * `@IsString()`: un `''` colado fallaría tres pasos río abajo en vez de en el boundary.
+     */
+    @Expose() @IsString() @IsNotEmpty()
+    directoryId!: string;
+
+    /** Identidad Fiado del cliente. Opcional: el productor publica `''` cuando Metamap no lo manda. */
+    @Expose() @IsOptional() @IsString()
+    peopleId?: string;
+
+    /** Por qué el comprobante quedó como quedó — el motivo legible, no solo si sirvió. */
+    @Expose() @IsEnum(ProofAddressStatusEnum)
+    status!: ProofAddressStatusEnum;
+
+    /**
+     * ¿Quedó un domicilio en el expediente del cliente? Va explícito aunque sea derivable del
+     * `status`: sin él cada consumidor reimplementaría el mapa de 12 casos que conoce el productor.
+     */
+    @Expose() @IsBoolean()
+    addressPersisted!: boolean;
+
+    /**
+     * Cuándo se cerró el comprobante. **Obligatorio:** la cola es SQS estándar, que no garantiza
+     * orden, y el consumidor descarta lo que llega más viejo que lo que ya escribió.
+     *
+     * ⚠️ **UTC estricto, con `Z` y sin offset** — por eso el `@Matches` además del `@IsISO8601()`.
+     * `@IsISO8601()` solo acepta `2026-08-11T15:05:00+05:00`, y ese es el que hace daño: léxicamente
+     * es "mayor" que un `T10:06:00Z` posterior, así que el consumidor descarta el evento real y nada
+     * truena. Normalizar a UTC es trabajo del webhook; este candado lo manda al DLQ si deja de hacerlo.
+     */
+    @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-08-11T10:05:00.000Z): un offset rompe el orden léxico',
+    })
+    occurredAt!: string;
+}

package/src/kyc/index.ts

@@ -4,6 +4,7 @@ export * from './enums/KycVerificationStatusEnum';
 export * from './enums/KycSubCheckStatusEnum';
 export * from './enums/KycWatchlistStatusEnum';
 export * from './enums/KycSubCheckNameEnum';
+export * from './enums/ProofAddressStatusEnum';
 
 // Sub-pasos descompuestos (SureKeep F2)
 export * from './dtos/KycSubChecks';
@@ -24,3 +25,4 @@ export * from './dtos/responses/KycByDirectoryResponse';
 // Events
 export * from './events/KycVerificationChangedV1';
 export * from './events/KycStepCompletedV1';
+export * from './events/KycProofOfAddressCompletedV1';

package/src/retailWizard/dtos/requests/ProofOfAddressPrepareRequest.ts

@@ -0,0 +1,15 @@
+import { Expose } from 'class-transformer';
+import { IsIn } from 'class-validator';
+import { KycModalityInput } from './KycPrepareRequest';
+
+/**
+ * POST /wizard/sessions/:id/proof-of-address/prepare — prepara el flujo del COMPROBANTE DE
+ * DOMICILIO de Metamap. Gemelo de `KycPrepareRequest` para el otro flow.
+ * `modality` = link al cliente o captura en tablet.
+ * SureKeep Fase 2 — pista Retail.
+ */
+export class ProofOfAddressPrepareRequest {
+  @Expose()
+  @IsIn(['CUSTOMER_LINK', 'STORE_DEVICE'])
+  modality!: KycModalityInput;
+}

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

@@ -48,6 +48,22 @@ export interface KycSdkMetadata {
      * no código.
      */
     source?: KycMetadataSourceEnum;
+    /**
+     * Paso del onboarding que originó la verificación. Es lo único que distingue al comprobante de
+     * domicilio del documento de identidad: `kyc-metamap-webhook` rutea por este campo.
+     */
+    kycStep?: KycMetadataStepEnum;
+}
+
+/**
+ * Paso del onboarding que originó una verificación, tal como viaja en `KycSdkMetadata.kycStep`.
+ *
+ * Enum y no string libre por el mismo motivo que `KycMetadataSourceEnum`: el valor lo escribe un
+ * repo (`retail-wizard-business`) y lo compara otro (`kyc-metamap-webhook`). Un typo dejaría al
+ * webhook procesando el comprobante como si fuera un documento de identidad, sin un solo error.
+ */
+export enum KycMetadataStepEnum {
+    PROOF_OF_ADDRESS = 'PROOF_OF_ADDRESS',
 }
 
 /**

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

@@ -0,0 +1,27 @@
+import { KycModalityEnum } from '../../../retailCustomer/enums/KycModalityEnum';
+
+/**
+ * POST /wizard/sessions/:id/proof-of-address/prepare — respuesta. Gemelo de `KycPrepareResponse`
+ * para el flow del comprobante de domicilio; la metadata del SDK es la misma `KycSdkMetadata` y la
+ * marca de que es comprobante viaja en su `kycStep`.
+ *
+ * **Bifurca por modalidad**, por eso todo es opcional salvo `modality`:
+ * - `STORE_DEVICE` → `clientId` + `flowId` + `metadata` para montar el `<metamap-button>` en la tablet.
+ * - `CUSTOMER_LINK` → `shortUrl` para el QR / SMS al teléfono del cliente.
+ *
+ * SureKeep Fase 2 — pista Retail.
+ */
+export interface ProofOfAddressPrepareResponse {
+    /** `MANUAL` no es una modalidad de `prepare`: la captura manual es su propio endpoint. */
+    modality: KycModalityEnum.CUSTOMER_LINK | KycModalityEnum.STORE_DEVICE;
+    /** STORE_DEVICE — clientId de la cuenta Metamap (mismo valor en prod y dev). */
+    clientId?: string;
+    /** STORE_DEVICE — flow de Metamap del comprobante de domicilio. */
+    flowId?: string;
+    /** STORE_DEVICE — `KycSdkMetadata` serializada en base64. */
+    metadata?: string;
+    /** CUSTOMER_LINK — link corto para el QR o el SMS. */
+    shortUrl?: string;
+    /** El expediente ya tiene domicilio principal: no hay comprobante que pedir. */
+    alreadyHasAddress?: boolean;
+}

package/src/retailWizard/index.ts

@@ -51,6 +51,7 @@ export * from './dtos/requests/ConsentsRequest';
 export * from './dtos/requests/KycPrepareRequest';
 export * from './dtos/requests/KycConfirmRequest';
 export * from './dtos/requests/KycManualRequest';
+export * from './dtos/requests/ProofOfAddressPrepareRequest';
 export * from './dtos/requests/OccupationRequest';
 export * from './dtos/requests/AddProductRequest';
 export * from './dtos/requests/DeleteProductRequest';
@@ -76,6 +77,7 @@ export * from './dtos/requests/RegisterDeviceRequest';
 
 // Response DTOs (output tipado por endpoint)
 export * from './dtos/responses/KycPrepareResponse';
+export * from './dtos/responses/ProofOfAddressPrepareResponse';
 export * from './dtos/responses/SessionFinanciersResponse';
 export * from './dtos/responses/ScoreConsultResponse';
 export * from './dtos/responses/ScoreResultResponse';