@fiado/type-kit 3.194.0 → 3.195.0

package/bin/retailWizard/events/SaleCancelledV1.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Emitido al cancelar una venta (flujo C). Se escribe al outbox transaccional; drena a la cola Central.
+ * SureKeep Fase 2 — pista Retail.
+ */
+export interface SaleCancelledV1 {
+    saleId: string;
+    folio: string;
+    retailCustomerId: string;
+    imei: string | null;
+    cancelReason: string;
+    cancelledAt: string;
+    occurredAt: string;
+}

package/bin/retailWizard/events/SaleCancelledV1.js

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

package/bin/retailWizard/events/SaleCompletedV1.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Emitido al cerrar una venta (flujo 09). Se escribe al outbox transaccional en la MISMA
+ * `TransactWriteItems` del cierre; drena a la cola Central + datalake. Solo identificadores
+ * operacionales (nunca PII). SureKeep Fase 2 — pista Retail.
+ */
+export interface SaleCompletedV1 {
+    saleId: string;
+    folio: string;
+    retailerId: string;
+    storeId: string;
+    retailCustomerId: string;
+    sku: string;
+    imei: string | null;
+    amountCents: number;
+    soldAt: string;
+    occurredAt: string;
+}

package/bin/retailWizard/events/SaleCompletedV1.js

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

package/bin/retailWizard/events/SessionExpiredV1.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Emitido cuando una sesión del wizard expira por inactividad (barrido del scheduler, TTL DDB ~24h).
+ * Libera la reserva del silo si la hubiera. SureKeep Fase 2 — pista Retail.
+ */
+export interface SessionExpiredV1 {
+    sessionId: string;
+    phone: string;
+    reservedImei: string | null;
+    occurredAt: string;
+}

package/bin/retailWizard/events/SessionExpiredV1.js

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

package/bin/retailWizard/index.d.ts

@@ -0,0 +1,54 @@
+export * from './enums/WizardStateEnum';
+export * from './enums/WizardStepEnum';
+export * from './enums/OtpPurposeEnum';
+export * from './enums/FiadoPhoneStatusEnum';
+export * from './enums/PaymentMethodEnum';
+export * from './enums/ExternalProviderEnum';
+export * from './enums/SaleTypeEnum';
+export * from './enums/SalePaymentMethodEnum';
+export * from './enums/SaleStatusEnum';
+export * from './enums/CentralSyncStatusEnum';
+export * from './enums/ProspectStatusEnum';
+export * from './enums/PendingReasonEnum';
+export * from './enums/OccupationEnum';
+export * from './enums/BeneficiaryRelationEnum';
+export * from './dtos/WizardConsents';
+export * from './dtos/WizardPayment';
+export * from './dtos/WizardWelcome';
+export * from './dtos/SalePaymentDetail';
+export * from './dtos/ProspectNewCustomer';
+export * from './dtos/WizardBeneficiary';
+export * from './dtos/WizardSession';
+export * from './dtos/OtpVerification';
+export * from './dtos/Sale';
+export * from './dtos/Prospect';
+export * from './dtos/PaginatedResult';
+export * from './dtos/requests/StartSessionRequest';
+export * from './dtos/requests/CancelSessionRequest';
+export * from './dtos/requests/VerifyOtpRequest';
+export * from './dtos/requests/ResendOtpRequest';
+export * from './dtos/requests/SkipOtpRequest';
+export * from './dtos/requests/ConsentsRequest';
+export * from './dtos/requests/KycPrepareRequest';
+export * from './dtos/requests/KycConfirmRequest';
+export * from './dtos/requests/KycManualRequest';
+export * from './dtos/requests/OccupationRequest';
+export * from './dtos/requests/AddProductRequest';
+export * from './dtos/requests/DeleteProductRequest';
+export * from './dtos/requests/SetPaymentMethodRequest';
+export * from './dtos/requests/ExternalReferralRequest';
+export * from './dtos/requests/RegisterPaymentRequest';
+export * from './dtos/requests/CompleteSaleRequest';
+export * from './dtos/requests/AppInstallLinkRequest';
+export * from './dtos/requests/MarkPcfCardDeliveredRequest';
+export * from './dtos/requests/ConfirmAddressRequest';
+export * from './dtos/requests/SaveBeneficiaryRequest';
+export * from './dtos/requests/SignBeneficiaryAnnexRequest';
+export * from './dtos/requests/WelcomeTopupRequest';
+export * from './dtos/requests/CreateProspectRequest';
+export * from './dtos/requests/UpdateProspectRequest';
+export * from './dtos/requests/MarkProspectLostRequest';
+export * from './dtos/requests/CancelSaleRequest';
+export * from './events/SaleCompletedV1';
+export * from './events/SaleCancelledV1';
+export * from './events/SessionExpiredV1';

package/bin/retailWizard/index.js

@@ -0,0 +1,76 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Enums
+__exportStar(require("./enums/WizardStateEnum"), exports);
+__exportStar(require("./enums/WizardStepEnum"), exports);
+__exportStar(require("./enums/OtpPurposeEnum"), exports);
+__exportStar(require("./enums/FiadoPhoneStatusEnum"), exports);
+__exportStar(require("./enums/PaymentMethodEnum"), exports);
+__exportStar(require("./enums/ExternalProviderEnum"), exports);
+__exportStar(require("./enums/SaleTypeEnum"), exports);
+__exportStar(require("./enums/SalePaymentMethodEnum"), exports);
+__exportStar(require("./enums/SaleStatusEnum"), exports);
+__exportStar(require("./enums/CentralSyncStatusEnum"), exports);
+__exportStar(require("./enums/ProspectStatusEnum"), exports);
+__exportStar(require("./enums/PendingReasonEnum"), exports);
+__exportStar(require("./enums/OccupationEnum"), exports);
+__exportStar(require("./enums/BeneficiaryRelationEnum"), exports);
+// DTOs anidados
+__exportStar(require("./dtos/WizardConsents"), exports);
+__exportStar(require("./dtos/WizardPayment"), exports);
+__exportStar(require("./dtos/WizardWelcome"), exports);
+__exportStar(require("./dtos/SalePaymentDetail"), exports);
+__exportStar(require("./dtos/ProspectNewCustomer"), exports);
+__exportStar(require("./dtos/WizardBeneficiary"), exports);
+// Entidades principales (shapes de estado/persistencia — planas)
+__exportStar(require("./dtos/WizardSession"), exports);
+__exportStar(require("./dtos/OtpVerification"), exports);
+__exportStar(require("./dtos/Sale"), exports);
+__exportStar(require("./dtos/Prospect"), exports);
+// Paginación genérica
+__exportStar(require("./dtos/PaginatedResult"), exports);
+// Request DTOs (input validado por endpoint)
+__exportStar(require("./dtos/requests/StartSessionRequest"), exports);
+__exportStar(require("./dtos/requests/CancelSessionRequest"), exports);
+__exportStar(require("./dtos/requests/VerifyOtpRequest"), exports);
+__exportStar(require("./dtos/requests/ResendOtpRequest"), exports);
+__exportStar(require("./dtos/requests/SkipOtpRequest"), exports);
+__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/OccupationRequest"), exports);
+__exportStar(require("./dtos/requests/AddProductRequest"), exports);
+__exportStar(require("./dtos/requests/DeleteProductRequest"), exports);
+__exportStar(require("./dtos/requests/SetPaymentMethodRequest"), exports);
+__exportStar(require("./dtos/requests/ExternalReferralRequest"), exports);
+__exportStar(require("./dtos/requests/RegisterPaymentRequest"), exports);
+__exportStar(require("./dtos/requests/CompleteSaleRequest"), exports);
+__exportStar(require("./dtos/requests/AppInstallLinkRequest"), exports);
+__exportStar(require("./dtos/requests/MarkPcfCardDeliveredRequest"), exports);
+__exportStar(require("./dtos/requests/ConfirmAddressRequest"), exports);
+__exportStar(require("./dtos/requests/SaveBeneficiaryRequest"), exports);
+__exportStar(require("./dtos/requests/SignBeneficiaryAnnexRequest"), exports);
+__exportStar(require("./dtos/requests/WelcomeTopupRequest"), exports);
+__exportStar(require("./dtos/requests/CreateProspectRequest"), exports);
+__exportStar(require("./dtos/requests/UpdateProspectRequest"), exports);
+__exportStar(require("./dtos/requests/MarkProspectLostRequest"), exports);
+__exportStar(require("./dtos/requests/CancelSaleRequest"), exports);
+// Contratos de eventos (PascalCase + sufijo V1)
+__exportStar(require("./events/SaleCompletedV1"), exports);
+__exportStar(require("./events/SaleCancelledV1"), exports);
+__exportStar(require("./events/SessionExpiredV1"), exports);

package/package.json

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

package/src/helpers/constans/regex.ts

@@ -7,6 +7,22 @@ export const regexIso8601 = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|
 // Expresión regular para validar un número de teléfono
 export const regexPhoneNumber = /^\+1\d{10}$|^\+52\d{10}$/;
 
+// Fecha ISO 8601 aceptando fecha sola (YYYY-MM-DD) o fecha-hora — p. ej. fecha de nacimiento del OCR,
+// que puede venir sin hora. Complementa a `regexIso8601` (estricto date-time, usado en createdAt/updatedAt).
+// Usado por los dominios retail F2 (retailCustomer). SureKeep Fase 2 — pista Retail.
+export const regexIso8601Date =
+  /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d{1,3})?(Z|[+-]\d{2}:\d{2})?)?$/;
+
+// CURP mexicano (18 chars): 4 letras + 6 dígitos de fecha + H/M + 5 letras entidad/consonantes + homoclave.
+// Se aplica SIEMPRE sobre el CURP en MAYÚSCULAS (normalización previa en el boundary).
+// Usado por retailCustomer (upsert-from-kyc). SureKeep Fase 2 — pista Retail.
+export const regexCurp =
+  /^[A-Z][AEIOUX][A-Z]{2}\d{2}(0[1-9]|1[0-2])(0[1-9]|[12]\d|3[01])[HM][A-Z]{2}[B-DF-HJ-NP-TV-Z]{3}[A-Z\d]\d$/;
+
+// Teléfono MX: exactamente 10 dígitos (se normalizan espacios/guiones antes de validar).
+// Usado por retailCustomer y retailWizard. SureKeep Fase 2 — pista Retail.
+export const regexPhoneMx = /^\d{10}$/;
+
 
 
 

package/src/index.ts

@@ -109,6 +109,12 @@ export * as RetailCatalog from './retailCatalog';
 // RetailCards: DTOs/enums del lambda retail-cards-business (comp 06 — tarjetas físicas PCF:
 // lotes, stock y asignación; SureKeep Fase 1 — pista Retail).
 export * as RetailCards from './retailCards';
+// RetailCustomer: DTOs/enums del lambda retail-customer-business (comp 03 — cliente comprador:
+// identidad Fiado, cuenta PCF async, domicilio y ciclo KYC con revisión de Cumplimiento; SureKeep Fase 2 — pista Retail).
+export * as RetailCustomer from './retailCustomer';
+// RetailWizard: DTOs/enums del lambda retail-wizard-business (comp 04 — wizard de venta de contado:
+// saga de sesión, OTP, KYC, venta y prospectos; SureKeep Fase 2 — pista Retail).
+export * as RetailWizard from './retailWizard';
 // LoanConfig: DTOs/enums del lambda loan-config-business (comp 09 — parámetros operativos del SOFOM).
 export * as LoanConfig from './loanConfig';
 // LoanOfferings: DTOs/enums del lambda loan-offerings-business (comp 07 — planes de crédito,

package/src/retailCustomer/dtos/KycReview.ts

@@ -0,0 +1,41 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsString, Matches } from 'class-validator';
+import { regexIso8601 } from '../../helpers/constans/regex';
+import { KycReviewResultEnum } from '../enums/KycReviewResultEnum';
+import { RetailKycStatusEnum } from '../enums/RetailKycStatusEnum';
+
+/**
+ * Aprobación/rechazo manual justificado del oficial de Cumplimiento (D21). Se persiste embebido en
+ * `RetailCustomer.kycReview` y se espeja a kyc-verifications (Fiado) + AuditTrail en la misma TX.
+ * SureKeep Fase 2 — pista Retail.
+ */
+export class KycReview {
+    @Expose()
+    @IsEnum(KycReviewResultEnum)
+    result!: KycReviewResultEnum;
+
+    /** Email del oficial (tomado del JWT). */
+    @Expose()
+    @IsString()
+    reviewedBy!: string;
+
+    @Expose()
+    @IsString()
+    @Matches(regexIso8601, { message: 'reviewedAt debe ser una fecha ISO 8601' })
+    reviewedAt!: string;
+
+    /** Justificación obligatoria de la decisión (queda en AuditTrail). */
+    @Expose()
+    @IsString()
+    justification!: string;
+
+    /** Correlación con la verificación de Metamap en kyc-verifications. */
+    @Expose()
+    @IsString()
+    metamapVerificationId!: string;
+
+    /** Estado de KYC previo a la resolución manual. */
+    @Expose()
+    @IsEnum(RetailKycStatusEnum)
+    previousStatus!: RetailKycStatusEnum;
+}

package/src/retailCustomer/dtos/RetailCustomer.ts

@@ -0,0 +1,132 @@
+import { Expose, Type } from 'class-transformer';
+import { IsBoolean, IsEnum, IsIn, IsOptional, IsString, Matches, ValidateNested } from 'class-validator';
+import { regexIso8601, regexIso8601Date } from '../../helpers/constans/regex';
+import { AddressBase } from '../../address/dtos/AddressBase';
+import { AccountStatusEnum } from '../enums/AccountStatusEnum';
+import { KycModalityEnum } from '../enums/KycModalityEnum';
+import { RetailKycStatusEnum } from '../enums/RetailKycStatusEnum';
+import { KycReview } from './KycReview';
+
+/**
+ * RetailCustomer — el comprador de la pista Retail (owner: retail-customer-business). Nace en F1 §3.5
+ * y se amplía en F2: vínculo con la identidad Fiado, cuenta PCF (apertura async, D35), domicilio
+ * estructurado (copia operativa del silo), y el ciclo de KYC con revisión manual de Cumplimiento.
+ * SureKeep Fase 2 — pista Retail.
+ */
+export class RetailCustomer {
+    @Expose()
+    @IsString()
+    retailCustomerId!: string;
+
+    @Expose()
+    @IsString()
+    retailerId!: string;
+
+    @Expose()
+    @IsString()
+    name!: string;
+
+    @Expose()
+    @IsString()
+    phone!: string;
+
+    @Expose()
+    @IsString()
+    curp!: string;
+
+    /** Fecha de nacimiento (ISO 8601, admite fecha sola); se completa con el OCR del KYC. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(regexIso8601Date, { message: 'birthDate debe ser una fecha ISO 8601' })
+    birthDate?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    fiadoDirectoryId!: string | null;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    fiadoPeopleId!: string | null;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    pcfAccountId!: string | null;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    pcfClabe!: string | null;
+
+    @Expose()
+    @IsOptional()
+    @IsIn([1, 2])
+    pcfAccountLevel!: 1 | 2 | null;
+
+    @Expose()
+    @IsOptional()
+    @IsEnum(AccountStatusEnum)
+    accountStatus!: AccountStatusEnum | null;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    failReason!: string | null;
+
+    @Expose()
+    @IsBoolean()
+    welcomeAccredited!: boolean;
+
+    // TD-ADDRESSBASE-OCR: por decisión de Andrés (2026-07) el domicilio reusa el `AddressBase` canónico
+    // de Fiado (`address/dtos/AddressBase`, espejo de Address_GT) tal cual manda el spec (componente 01 +
+    // modelo-datos F2). RIESGO detectado: `AddressBase` tiene ~12 campos requeridos (directoryId, tenantId,
+    // createdBy, typeOfAddressId, typeOfDirectoryId, provider, addressStatus, validFrom, isPrincipal,
+    // helpNeeded, countryId, country) que un domicilio de copia OCR-parcial puede NO llenar → con
+    // @ValidateNested esto puede RECHAZAR en runtime los payloads OCR de kyc/confirm y address/confirm.
+    // Se acepta ahora para apegarse al doc; ajustar después (posible tipo de dirección ligero para captura).
+    @Expose()
+    @IsOptional()
+    @ValidateNested()
+    @Type(() => AddressBase)
+    address!: AddressBase | null;
+
+    @Expose()
+    @IsBoolean()
+    addressConfirmed!: boolean;
+
+    @Expose()
+    @IsEnum(RetailKycStatusEnum)
+    kycStatus!: RetailKycStatusEnum;
+
+    @Expose()
+    @IsOptional()
+    @IsEnum(KycModalityEnum)
+    kycModality!: KycModalityEnum | null;
+
+    @Expose()
+    @IsOptional()
+    @ValidateNested()
+    @Type(() => KycReview)
+    kycReview!: KycReview | null;
+
+    @Expose()
+    @IsString()
+    @Matches(regexIso8601, { message: 'createdAt debe ser una fecha ISO 8601' })
+    createdAt!: string;
+
+    @Expose()
+    @IsString()
+    @Matches(regexIso8601, { message: 'updatedAt debe ser una fecha ISO 8601' })
+    updatedAt!: string;
+
+    @Expose()
+    @IsString()
+    createdBy!: string;
+
+    @Expose()
+    @IsString()
+    updatedBy!: string;
+}

package/src/retailCustomer/dtos/requests/AccountResultRequest.ts

@@ -0,0 +1,34 @@
+import { Expose } from 'class-transformer';
+import { IsIn, IsNotEmpty, IsOptional, IsString, ValidateIf } from 'class-validator';
+import { AccountStatusEnum } from '../../enums/AccountStatusEnum';
+
+/**
+ * Resultado de la apertura de cuenta async (D35) — lo escribe el consumer `account-inbound` al
+ * aterrizar el evento `AccountIssuanceCompleted`. OPEN llega con `pcfClabe`/`pcfAccountLevel`;
+ * FAILED llega con `failReason`. El endpoint SOLO acepta el resultado terminal (OPEN/FAILED), nunca
+ * el estado intermedio OPENING (ese lo setea el server en el upsert). SureKeep Fase 2 — pista Retail.
+ */
+export class AccountResultRequest {
+    // OPENING NO es un resultado válido del endpoint D35; solo el estado terminal OPEN/FAILED.
+    @Expose()
+    @IsIn([AccountStatusEnum.OPEN, AccountStatusEnum.FAILED])
+    status!: AccountStatusEnum;
+
+    // OPEN ⇒ pcfClabe obligatorio (la cuenta abierta sin CLABE es inconsistente). Para FAILED se omite
+    // (@ValidateIf desactiva los validators cuando status ≠ OPEN → queda opcional).
+    @Expose()
+    @ValidateIf((o: AccountResultRequest) => o.status === AccountStatusEnum.OPEN)
+    @IsString()
+    @IsNotEmpty({ message: 'pcfClabe es obligatorio cuando status es OPEN' })
+    pcfClabe?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsIn([1, 2])
+    pcfAccountLevel?: 1 | 2;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    failReason?: string;
+}

package/src/retailCustomer/dtos/requests/CreateCustomerRequest.ts

@@ -0,0 +1,28 @@
+import { Expose } from 'class-transformer';
+import { IsOptional, IsString, Matches } from 'class-validator';
+import { regexIso8601Date } from '../../../helpers/constans/regex';
+
+/**
+ * Alta básica de un cliente retail (identidad comercial mínima; el KYC la enriquece después).
+ * SureKeep Fase 2 — pista Retail.
+ */
+export class CreateCustomerRequest {
+    @Expose()
+    @IsString()
+    name!: string;
+
+    @Expose()
+    @IsString()
+    phone!: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    curp?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(regexIso8601Date, { message: 'birthDate debe ser una fecha ISO 8601' })
+    birthDate?: string;
+}

package/src/retailCustomer/dtos/requests/KycReviewRequest.ts

@@ -0,0 +1,18 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsString } from 'class-validator';
+import { KycReviewResultEnum } from '../../enums/KycReviewResultEnum';
+
+/**
+ * Resolución de la cola de Cumplimiento (D21): `POST /customers/:id/kyc-review`. La `justification`
+ * es OBLIGATORIA (queda en AuditTrail). `reviewedBy`/`reviewedAt` los pone el server.
+ * SureKeep Fase 2 — pista Retail.
+ */
+export class KycReviewRequest {
+    @Expose()
+    @IsEnum(KycReviewResultEnum)
+    result!: KycReviewResultEnum;
+
+    @Expose()
+    @IsString()
+    justification!: string;
+}

package/src/retailCustomer/dtos/requests/UpdateCustomerRequest.ts

@@ -0,0 +1,30 @@
+import { Expose } from 'class-transformer';
+import { IsOptional, IsString, Matches } from 'class-validator';
+import { regexIso8601Date } from '../../../helpers/constans/regex';
+
+/**
+ * Edición de datos de contacto/PII del cliente (Cliente 360 del BO). Toda escritura de PII va a
+ * AuditTrail + PiiAccessLog en el lambda. SureKeep Fase 2 — pista Retail.
+ */
+export class UpdateCustomerRequest {
+    @Expose()
+    @IsOptional()
+    @IsString()
+    name?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    phone?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    curp?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(regexIso8601Date, { message: 'birthDate debe ser una fecha ISO 8601' })
+    birthDate?: string;
+}

package/src/retailCustomer/dtos/requests/UpsertCustomerFromKycRequest.ts

@@ -0,0 +1,79 @@
+import { Expose, Transform, Type } from 'class-transformer';
+import { IsEnum, IsIn, IsOptional, IsString, Matches, ValidateNested } from 'class-validator';
+import { regexCurp, regexIso8601Date, regexPhoneMx } from '../../../helpers/constans/regex';
+import { AddressBase } from '../../../address/dtos/AddressBase';
+import { KycModalityEnum } from '../../enums/KycModalityEnum';
+import { RetailKycStatusEnum } from '../../enums/RetailKycStatusEnum';
+
+/**
+ * Upsert idempotente del cliente tras el KYC (paso 02f). UNIQ#PHONE + UNIQ#CURP en la misma TX.
+ * El endpoint setea `accountStatus=OPENING` server-side (la apertura corre en background, D35).
+ * SureKeep Fase 2 — pista Retail.
+ */
+export class UpsertCustomerFromKycRequest {
+    @Expose()
+    @IsString()
+    name!: string;
+
+    // Normalización en el boundary: se strippean espacios/guiones para que centinela de unicidad,
+    // lookup y search del BO (que también strippea) usen el MISMO formato de teléfono.
+    @Expose()
+    @Transform(({ value }) => (typeof value === 'string' ? value.replace(/[\s-]/g, '') : value))
+    @IsString()
+    @Matches(regexPhoneMx, { message: 'phone debe ser 10 dígitos MX' })
+    phone!: string;
+
+    // Normalización en el boundary: el CURP se uppercasea para no evadir la unicidad transaccional
+    // (minúsculas vs mayúsculas) y para que el search del BO (que uppercasea) lo encuentre.
+    @Expose()
+    @Transform(({ value }) => (typeof value === 'string' ? value.toUpperCase() : value))
+    @IsString()
+    @Matches(regexCurp, { message: 'curp con formato inválido' })
+    curp!: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(regexIso8601Date, { message: 'birthDate debe ser una fecha ISO 8601' })
+    birthDate?: string;
+
+    @Expose()
+    @IsString()
+    fiadoDirectoryId!: string;
+
+    @Expose()
+    @IsString()
+    fiadoPeopleId!: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    pcfAccountId?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    pcfClabe?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsIn([1, 2])
+    pcfAccountLevel?: 1 | 2;
+
+    @Expose()
+    @IsEnum(RetailKycStatusEnum)
+    kycStatus!: RetailKycStatusEnum;
+
+    @Expose()
+    @IsEnum(KycModalityEnum)
+    kycModality!: KycModalityEnum;
+
+    // TD-ADDRESSBASE-OCR: reusa el `AddressBase` canónico por decisión de Andrés (apego al spec). El OCR
+    // (paso 02e) puede no traer los ~12 campos requeridos de AddressBase → posible rechazo en runtime con
+    // @ValidateNested. Se persiste en la MISMA TX del upsert. Ajustar después (ver RetailCustomer.address).
+    @Expose()
+    @IsOptional()
+    @ValidateNested()
+    @Type(() => AddressBase)
+    address?: AddressBase;
+}

package/src/retailCustomer/dtos/responses/Customer360Response.ts

@@ -0,0 +1,37 @@
+import { CustomerResponse } from './CustomerResponse';
+
+/** Resumen de wallet (nivel N1/N2 + saldo) para el Cliente 360. */
+export interface Customer360Wallet {
+    accountLevel: 1 | 2 | null;
+    clabe: string | null;
+    balanceCents: number;
+}
+
+/** Ítem de compra en el historial del Cliente 360 (del GSI customerId-soldAt). */
+export interface Customer360Purchase {
+    saleId: string;
+    sku: string;
+    amountCents: number;
+    folio: string;
+    soldAt: string;
+    status: string;
+}
+
+/** Ítem de prospecto vinculado al cliente en el Cliente 360. */
+export interface Customer360Prospect {
+    prospectId: string;
+    pendingReason: string;
+    status: string;
+    nextContactAt: string;
+}
+
+/**
+ * Ficha Cliente 360 (BO): compone KYC + wallet N1/N2 + compras + prospectos. Cada bloque se hidrata
+ * desde su owner (customer, transaction-processor, sale GSI, prospect GSI). SureKeep Fase 2 — pista Retail.
+ */
+export interface Customer360Response {
+    customer: CustomerResponse;
+    wallet: Customer360Wallet;
+    purchases: Customer360Purchase[];
+    prospects: Customer360Prospect[];
+}