@fiado/type-kit 3.194.0 → 3.196.0

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

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

@@ -0,0 +1,31 @@
+import { AddressBase } from '../../../address/dtos/AddressBase';
+import { AccountStatusEnum } from '../../enums/AccountStatusEnum';
+import { KycModalityEnum } from '../../enums/KycModalityEnum';
+import { RetailKycStatusEnum } from '../../enums/RetailKycStatusEnum';
+
+/**
+ * Vista de un cliente retail hacia el consumidor (BO / api-invoker). SureKeep Fase 2 — pista Retail.
+ * `address` reusa el `AddressBase` canónico de Fiado (ver TD en RetailCustomer.address).
+ */
+export interface CustomerResponse {
+    retailCustomerId: string;
+    retailerId: string;
+    name: string;
+    phone: string;
+    curp: string;
+    birthDate: string | null;
+    fiadoDirectoryId: string | null;
+    fiadoPeopleId: string | null;
+    pcfAccountId: string | null;
+    pcfClabe: string | null;
+    pcfAccountLevel: 1 | 2 | null;
+    accountStatus: AccountStatusEnum | null;
+    failReason: string | null;
+    welcomeAccredited: boolean;
+    address: AddressBase | null;
+    addressConfirmed: boolean;
+    kycStatus: RetailKycStatusEnum;
+    kycModality: KycModalityEnum | null;
+    createdAt: string;
+    updatedAt: string;
+}

package/src/retailCustomer/enums/AccountStatusEnum.ts

@@ -0,0 +1,9 @@
+/**
+ * Estado de la apertura async de la cuenta PagoConFiado (PCF) del cliente retail (D35).
+ * SureKeep Fase 2 — pista Retail.
+ */
+export enum AccountStatusEnum {
+    OPENING = 'OPENING',
+    OPEN = 'OPEN',
+    FAILED = 'FAILED',
+}

package/src/retailCustomer/enums/KycModalityEnum.ts

@@ -0,0 +1,9 @@
+/**
+ * Modalidad con la que el cliente ejecuta el KYC en el wizard (M1 §213-329).
+ * SureKeep Fase 2 — pista Retail.
+ */
+export enum KycModalityEnum {
+    CUSTOMER_LINK = 'CUSTOMER_LINK',
+    STORE_DEVICE = 'STORE_DEVICE',
+    MANUAL = 'MANUAL',
+}

package/src/retailCustomer/enums/KycReviewResultEnum.ts

@@ -0,0 +1,8 @@
+/**
+ * Resultado de la revisión manual del oficial de Cumplimiento (D21).
+ * SureKeep Fase 2 — pista Retail.
+ */
+export enum KycReviewResultEnum {
+    APPROVED = 'APPROVED',
+    REJECTED = 'REJECTED',
+}

package/src/retailCustomer/enums/RetailKycStatusEnum.ts

@@ -0,0 +1,13 @@
+/**
+ * Estado del KYC del cliente retail (vocabulario retail; espejo operativo del KYC de Fiado).
+ * PENDING (sin resultado) · VERIFIED (Metamap OK) · FAILED (incluye PLD) · MANUAL (captura manual,
+ * cae en cola de Cumplimiento) · REVIEW (esperando resolución de Cumplimiento).
+ * SureKeep Fase 2 — pista Retail.
+ */
+export enum RetailKycStatusEnum {
+    PENDING = 'PENDING',
+    VERIFIED = 'VERIFIED',
+    FAILED = 'FAILED',
+    MANUAL = 'MANUAL',
+    REVIEW = 'REVIEW',
+}

package/src/retailCustomer/events/CustomerCreatedV1.ts

@@ -0,0 +1,7 @@
+/** Emitido cuando se da de alta un cliente retail (→ cola Central). SureKeep Fase 2 — pista Retail. */
+export interface CustomerCreatedV1 {
+    retailCustomerId: string;
+    retailerId: string;
+    phone: string;
+    occurredAt: string;
+}

package/src/retailCustomer/events/CustomerKycVerifiedV1.ts

@@ -0,0 +1,28 @@
+import { KycModalityEnum } from '../enums/KycModalityEnum';
+import { RetailKycStatusEnum } from '../enums/RetailKycStatusEnum';
+
+/**
+ * Puente retail↔sofom (D24/D35) — emitido en la MISMA TX del `upsert-from-kyc` con el payload OCR
+ * completo. Lo consume `loan-credit-business` (idempotente, hidrata `LoanBorrower_GT`) y dispara la
+ * apertura de cuenta async. También alimenta CDC→Iceberg (atomicidad efectiva por outbox).
+ * SureKeep Fase 2 — pista Retail.
+ */
+export interface CustomerKycVerifiedV1 {
+    retailCustomerId: string;
+    retailerId: string;
+    fiadoDirectoryId: string;
+    fiadoPeopleId: string;
+    phone: string;
+    curp: string;
+    firstName: string;
+    paternalLastName: string;
+    maternalLastName: string | null;
+    birthDate: string;
+    sex: string | null;
+    nationality: string | null;
+    documentValidUntil: string | null;
+    addressRaw: string | null;
+    kycStatus: RetailKycStatusEnum;
+    kycModality: KycModalityEnum;
+    occurredAt: string;
+}

package/src/retailCustomer/events/CustomerUpdatedV1.ts

@@ -0,0 +1,9 @@
+/** Emitido cuando se editan datos de contacto/PII de un cliente retail. SureKeep Fase 2 — pista Retail. */
+export interface CustomerUpdatedV1 {
+    retailCustomerId: string;
+    retailerId: string;
+    /** Nombres de los campos modificados (sin sus valores — PII zero-tolerance). */
+    updatedFields: string[];
+    updatedBy: string;
+    occurredAt: string;
+}

package/src/retailCustomer/events/KycApprovedByComplianceV1.ts

@@ -0,0 +1,12 @@
+/**
+ * Emitido cuando el oficial de Cumplimiento APRUEBA un KYC en revisión manual (D21). Dispara post-pasos
+ * idempotentes fuera de la TX (espejo a Fiado + apertura PCF N1 diferida). SureKeep Fase 2 — pista Retail.
+ */
+export interface KycApprovedByComplianceV1 {
+    retailCustomerId: string;
+    retailerId: string;
+    reviewedBy: string;
+    justification: string;
+    metamapVerificationId: string;
+    occurredAt: string;
+}

package/src/retailCustomer/events/KycRejectedByComplianceV1.ts

@@ -0,0 +1,12 @@
+/**
+ * Emitido cuando el oficial de Cumplimiento RECHAZA un KYC en revisión manual (D21).
+ * SureKeep Fase 2 — pista Retail.
+ */
+export interface KycRejectedByComplianceV1 {
+    retailCustomerId: string;
+    retailerId: string;
+    reviewedBy: string;
+    justification: string;
+    metamapVerificationId: string;
+    occurredAt: string;
+}

package/src/retailCustomer/index.ts

@@ -0,0 +1,27 @@
+// Enums
+export * from './enums/AccountStatusEnum';
+export * from './enums/RetailKycStatusEnum';
+export * from './enums/KycModalityEnum';
+export * from './enums/KycReviewResultEnum';
+
+// Entidades (planas, con class-validator + @Expose)
+export * from './dtos/KycReview';
+export * from './dtos/RetailCustomer';
+
+// Request DTOs (input validado por endpoint)
+export * from './dtos/requests/CreateCustomerRequest';
+export * from './dtos/requests/UpsertCustomerFromKycRequest';
+export * from './dtos/requests/UpdateCustomerRequest';
+export * from './dtos/requests/AccountResultRequest';
+export * from './dtos/requests/KycReviewRequest';
+
+// Response DTOs
+export * from './dtos/responses/CustomerResponse';
+export * from './dtos/responses/Customer360Response';
+
+// Contratos de eventos (PascalCase + sufijo V1)
+export * from './events/CustomerCreatedV1';
+export * from './events/CustomerUpdatedV1';
+export * from './events/CustomerKycVerifiedV1';
+export * from './events/KycApprovedByComplianceV1';
+export * from './events/KycRejectedByComplianceV1';

package/src/retailWizard/dtos/OtpVerification.ts

@@ -0,0 +1,25 @@
+import type { OtpPurposeEnum } from '../enums/OtpPurposeEnum';
+
+/**
+ * Verificación OTP (modelo-datos §2). NO es tabla aparte: vive como ítem en
+ * `<T>RetailWizardSession_GT` (pk `SESSION#<sessionId>` · sk `OTP#<ulid>`) — misma partición de la
+ * sesión → 1 Query trae sesión + OTPs. El código lo genera/valida `messages-business` (D5); aquí
+ * solo trackeamos el `messagesLogId`, nunca el código. SureKeep Fase 2 — pista Retail.
+ */
+export interface OtpVerification {
+  otpId: string;
+  sessionId: string;
+  purpose: OtpPurposeEnum;
+  /** Sustituye al `code_hash` de v0.1 (D5): tracking del envío en messages-business. */
+  messagesLogId: string;
+  channelsDispatched: string[];
+  /** Máx 3 → 423 OTP_MAX_TRIES. */
+  attempts: number;
+  /** 5 min. */
+  expiresAt: string;
+  verifiedAt: string | null;
+  createdBy: string;
+  updatedBy: string;
+  createdAt: number;
+  updatedAt: number;
+}

package/src/retailWizard/dtos/PaginatedResult.ts

@@ -0,0 +1,6 @@
+/** Resultado paginado genérico (cursor opaco `nextToken`). SureKeep Fase 2 — pista Retail. */
+export interface PaginatedResult<T> {
+  items: T[];
+  count: number;
+  nextToken?: string;
+}

package/src/retailWizard/dtos/Prospect.ts

@@ -0,0 +1,33 @@
+import type { ProspectStatusEnum } from '../enums/ProspectStatusEnum';
+import type { PendingReasonEnum } from '../enums/PendingReasonEnum';
+import type { ProspectNewCustomer } from './ProspectNewCustomer';
+
+/**
+ * Prospecto (modelo-datos §4). pk `PROSPECT#<prospectId>` · sk `META` · GSIs
+ * `storeId-nextContactAt-index`, `seller-nextContactAt-index`. La reanudación lee la WizardSession
+ * real (no se duplica el snapshot del wizard). SureKeep Fase 2 — pista Retail.
+ */
+export interface Prospect {
+  prospectId: string;
+  retailerId: string;
+  storeId: string;
+  sellerRetailUserId: string;
+  /** Identificado vs captura manual (uno de los dos). */
+  retailCustomerId: string | null;
+  newCustomer: ProspectNewCustomer | null;
+  productSku: string | null;
+  pendingReason: PendingReasonEnum;
+  /** Obligatorio si `pendingReason=OTHER`; ≤200. */
+  freeReason: string | null;
+  /** Agenda (default mañana); urgencia derivada OVERDUE/TODAY/UPCOMING. */
+  nextContactAt: string;
+  notes: string | null;
+  status: ProspectStatusEnum;
+  wizardSessionId: string | null;
+  saleId: string | null;
+  lastContactAt: string | null;
+  createdBy: string;
+  updatedBy: string;
+  createdAt: number;
+  updatedAt: number;
+}

package/src/retailWizard/dtos/ProspectNewCustomer.ts

@@ -0,0 +1,13 @@
+import { Expose } from 'class-transformer';
+import { IsString } from 'class-validator';
+
+/** Captura manual de un cliente no identificado en un prospecto (`Prospect.newCustomer`). SureKeep Fase 2 — pista Retail. */
+export class ProspectNewCustomer {
+    @Expose()
+    @IsString()
+    name!: string;
+
+    @Expose()
+    @IsString()
+    phone!: string;
+}

package/src/retailWizard/dtos/Sale.ts

@@ -0,0 +1,43 @@
+import type { SaleTypeEnum } from '../enums/SaleTypeEnum';
+import type { SaleStatusEnum } from '../enums/SaleStatusEnum';
+import type { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+import type { ExternalProviderEnum } from '../enums/ExternalProviderEnum';
+import type { CentralSyncStatusEnum } from '../enums/CentralSyncStatusEnum';
+import type { SalePaymentDetail } from './SalePaymentDetail';
+
+/**
+ * Venta (modelo-datos §3). pk `SALE#<saleId>` · sk `META` · 4 GSIs (`retailerId-soldAt-index`,
+ * `storeId-soldAt-index`, `seller-soldAt-index`, `customerId-soldAt-index`). Unicidad de folio vía
+ * `UNIQ#FOLIO#<folio>` en la MISMA TransactWriteItems del cierre. SureKeep Fase 2 — pista Retail.
+ */
+export interface Sale {
+  saleId: string;
+  retailerId: string;
+  storeId: string;
+  sellerRetailUserId: string;
+  retailCustomerId: string;
+  wizardSessionId: string;
+  type: SaleTypeEnum;
+  externalProvider: ExternalProviderEnum | null;
+  sku: string;
+  /** IMEI consumido del silo también en contado (local-first); null en EXTERNAL_REFERRAL (D15). */
+  imei: string | null;
+  /** 0 en EXTERNAL_REFERRAL. */
+  amountCents: number;
+  paymentMethod: SalePaymentMethodEnum | null;
+  /** `LG-T{storeCode}-VTA-{5hex}-{YYYY}W{ww}` (D11) — único vía `UNIQ#FOLIO`. */
+  folio: string;
+  paymentDetail: SalePaymentDetail | null;
+  soldAt: string;
+  cardNumberDelivered: string | null;
+  centralSyncStatus: CentralSyncStatusEnum;
+  centralTag: string | null;
+  status: SaleStatusEnum;
+  cancelledAt: string | null;
+  /** Reason OBLIGATORIO en cancelación (AuditTrail) — flujo C. */
+  cancelReason: string | null;
+  createdBy: string;
+  updatedBy: string;
+  createdAt: number;
+  updatedAt: number;
+}

package/src/retailWizard/dtos/SalePaymentDetail.ts

@@ -0,0 +1,33 @@
+import { Expose } from 'class-transformer';
+import { IsBoolean, IsOptional, IsString } from 'class-validator';
+
+/**
+ * Detalle del pago según el medio (`Sale.paymentDetail`): efectivo `{cashConfirmedInRegister}` ·
+ * tarjeta `{cardLast4, authCode}` · SPEI `{speiTrackingKey, senderClabe?}`. SureKeep Fase 2 — pista Retail.
+ */
+export class SalePaymentDetail {
+    @Expose()
+    @IsOptional()
+    @IsBoolean()
+    cashConfirmedInRegister?: boolean;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    cardLast4?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    authCode?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    speiTrackingKey?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    senderClabe?: string;
+}

package/src/retailWizard/dtos/WizardBeneficiary.ts

@@ -0,0 +1,31 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsInt, IsOptional, IsString, Max, Min } from 'class-validator';
+import { BeneficiaryRelationEnum } from '../enums/BeneficiaryRelationEnum';
+
+/**
+ * Beneficiario capturado en el paso 10 (bienvenida N2). Se envía a `IAccountBeneficiaryApi.create`
+ * (expediente wallet Fiado). El cliente puede NO dar beneficiario (opcional en régimen simplificado N1).
+ * SureKeep Fase 2 — pista Retail.
+ */
+export class WizardBeneficiary {
+    @Expose()
+    @IsString()
+    fullName!: string;
+
+    @Expose()
+    @IsEnum(BeneficiaryRelationEnum)
+    relation!: BeneficiaryRelationEnum;
+
+    /** Porcentaje de asignación (1-100). Si hay un solo beneficiario, típicamente 100. */
+    @Expose()
+    @IsOptional()
+    @IsInt()
+    @Min(1)
+    @Max(100)
+    percentage?: number;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    freeRelation?: string;
+}

package/src/retailWizard/dtos/WizardConsents.ts

@@ -0,0 +1,29 @@
+import { Expose } from 'class-transformer';
+import { IsOptional, IsString, Matches } from 'class-validator';
+import { regexIso8601 } from '../../helpers/constans/regex';
+
+/** Consentimientos aceptados en el wizard (VL + contrato PCF). SureKeep Fase 2 — pista Retail. */
+export class WizardConsents {
+    @Expose()
+    @IsString()
+    vlTermsVersion!: string;
+
+    @Expose()
+    @IsString()
+    pcfContractVersion!: string;
+
+    @Expose()
+    @IsString()
+    @Matches(regexIso8601, { message: 'acceptedAt debe ser una fecha ISO 8601' })
+    acceptedAt!: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    ip?: string;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    deviceFingerprint?: string;
+}

package/src/retailWizard/dtos/WizardPayment.ts

@@ -0,0 +1,26 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsInt, IsOptional, IsString, Matches, Min } from 'class-validator';
+import { regexIso8601 } from '../../helpers/constans/regex';
+import { SalePaymentMethodEnum } from '../enums/SalePaymentMethodEnum';
+
+/** Registro del pago de contado dentro de la sesión (`WizardSession.payment`). SureKeep Fase 2 — pista Retail. */
+export class WizardPayment {
+    @Expose()
+    @IsEnum(SalePaymentMethodEnum)
+    method!: SalePaymentMethodEnum;
+
+    @Expose()
+    @IsInt()
+    @Min(0)
+    amountCents!: number;
+
+    @Expose()
+    @IsOptional()
+    @IsString()
+    detail?: string;
+
+    @Expose()
+    @IsString()
+    @Matches(regexIso8601, { message: 'paidAt debe ser una fecha ISO 8601' })
+    paidAt!: string;
+}