@fiado/type-kit 3.550.0 → 3.552.0

package/src/retailCommission/dtos/CommissionRule.ts

@@ -1,9 +1,11 @@
 import type { ProductCategoryEnum } from '../../retailCatalog/enums/ProductCategoryEnum';
 import type { ProductTierEnum } from '../../retailCatalog/enums/ProductTierEnum';
+import type { CommissionBillingPeriodEnum } from '../enums/CommissionBillingPeriodEnum';
 import type { CommissionBonusModeEnum } from '../enums/CommissionBonusModeEnum';
 import type { CommissionCountByEnum } from '../enums/CommissionCountByEnum';
 import type { CommissionMetricEnum } from '../enums/CommissionMetricEnum';
 import type { CommissionOperatorEnum } from '../enums/CommissionOperatorEnum';
+import type { CommissionPayTimingEnum } from '../enums/CommissionPayTimingEnum';
 import type { CommissionRuleStatusEnum } from '../enums/CommissionRuleStatusEnum';
 import type { CommissionWindowEnum } from '../enums/CommissionWindowEnum';
 
@@ -84,6 +86,8 @@ export interface CommissionRule {
     replacesOthers: boolean;
     /** Si la regla cuenta piezas o ventas. Ausente = `PIECE`. */
     countBy?: CommissionCountByEnum;
+    /** Cuándo se paga lo que gana. Ausente = `ON_CUT`. */
+    payTiming?: CommissionPayTimingEnum;
     /** Sube en cada guardado. */
     version: number;
     /** La versión que está en el plan vigente. `null` si nunca se publicó. */
@@ -114,10 +118,20 @@ export interface CommissionPolicyCommissions {
     editedAt: string;
 }
 
-/** Políticas de la cadena. Cada una es `null` mientras la cadena no la guarda. */
+/** Política de pagos a la wallet de los vendedores. */
+export interface CommissionPayoutPolicy {
+    /** Depositar las comisiones a la wallet. Apagado, todo se calcula y queda pendiente. */
+    walletDeposits: boolean;
+    /** Cada cuánto se le cobra a la cadena. */
+    chainBillingPeriod: CommissionBillingPeriodEnum;
+}
+
+/** Políticas de la cadena. `clawback` y `commissions` son `null` mientras la cadena no las guarda. */
 export interface CommissionPolicies {
     clawback: CommissionPolicyClawback | null;
     commissions: CommissionPolicyCommissions | null;
+    /** Ausente = depósitos encendidos y cobro semanal. */
+    payouts?: CommissionPayoutPolicy;
 }
 
 /**

package/src/retailCommission/enums/CommissionBillingPeriodEnum.ts

@@ -0,0 +1,10 @@
+/**
+ * Cada cuánto se le cobra a la cadena lo que Fiado depositó a sus vendedores.
+ *
+ * WEEKLY - Semanal. Es el valor cuando la cadena no guardó la política.
+ * MONTHLY - Mensual.
+ */
+export enum CommissionBillingPeriodEnum {
+    WEEKLY = 'WEEKLY',
+    MONTHLY = 'MONTHLY',
+}

package/src/retailCommission/enums/CommissionLedgerMovementKindEnum.ts

@@ -0,0 +1,14 @@
+/**
+ * Tipo de movimiento del libro de pagos. Un movimiento nunca cambia.
+ *
+ * EARN - Ganado: suma al exigible o al retenido.
+ * DEDUCT - Descontado del exigible.
+ * RELEASE - Liberación mensual: pasa de retenido a exigible.
+ * PAID_OUTSIDE - Pagado por fuera de la wallet: sale del exigible sin depósito.
+ */
+export enum CommissionLedgerMovementKindEnum {
+    EARN = 'EARN',
+    DEDUCT = 'DEDUCT',
+    RELEASE = 'RELEASE',
+    PAID_OUTSIDE = 'PAID_OUTSIDE',
+}

package/src/retailCommission/enums/CommissionPayTimingEnum.ts

@@ -0,0 +1,13 @@
+/**
+ * Cuándo se paga lo que gana una regla.
+ *
+ * ON_SALE - Al momento: se vuelve exigible al registrar la venta. Solo para reglas que únicamente
+ *   pagan bono por venta.
+ * ON_CUT - Al cierre de la semana. Es el valor cuando la regla no lo trae.
+ * MONTHLY - Al cierre del mes: se retiene hasta el día 1 del mes siguiente al lunes del corte.
+ */
+export enum CommissionPayTimingEnum {
+    ON_SALE = 'ON_SALE',
+    ON_CUT = 'ON_CUT',
+    MONTHLY = 'MONTHLY',
+}

package/src/retailCommission/enums/CommissionPayTriggerEnum.ts

@@ -0,0 +1,18 @@
+/**
+ * Qué pidió pagarle a un vendedor.
+ *
+ * SALE - Una venta con reglas al momento.
+ * CUT - El cierre del corte.
+ * RELEASE - La liberación mensual.
+ * ADJUSTMENT - Un ajuste manual.
+ * WALLET_LINKED - Se vinculó su wallet.
+ * RETRY - "Reintentar ahora" desde "Por pagar".
+ */
+export enum CommissionPayTriggerEnum {
+    SALE = 'SALE',
+    CUT = 'CUT',
+    RELEASE = 'RELEASE',
+    ADJUSTMENT = 'ADJUSTMENT',
+    WALLET_LINKED = 'WALLET_LINKED',
+    RETRY = 'RETRY',
+}

package/src/retailCommission/enums/CommissionPaymentAttentionEnum.ts

@@ -0,0 +1,14 @@
+/**
+ * Por qué el saldo de un vendedor aparece en "Por pagar".
+ *
+ * NO_WALLET - No tiene wallet vinculada.
+ * REJECTED - Su último depósito se rechazó (cuenta bloqueada, tope de nivel...); el código va aparte.
+ * PAUSED - La cadena apagó los depósitos a la wallet.
+ * DEBT - Su exigible es negativo: debe.
+ */
+export enum CommissionPaymentAttentionEnum {
+    NO_WALLET = 'NO_WALLET',
+    REJECTED = 'REJECTED',
+    PAUSED = 'PAUSED',
+    DEBT = 'DEBT',
+}

package/src/retailCommission/enums/CommissionPaymentStatusEnum.ts

@@ -0,0 +1,14 @@
+/**
+ * Estado de un depósito de comisiones a la wallet del vendedor.
+ *
+ * PENDING - El monto se apartó y el depósito está en curso.
+ * ACCREDITED - Depositado, con folio.
+ * FAILED - Rechazado sin mover dinero: el monto vuelve al exigible.
+ * UNVERIFIED - Resultado ambiguo: el monto sigue apartado y no se reintenta solo; alguien lo revisa.
+ */
+export enum CommissionPaymentStatusEnum {
+    PENDING = 'PENDING',
+    ACCREDITED = 'ACCREDITED',
+    FAILED = 'FAILED',
+    UNVERIFIED = 'UNVERIFIED',
+}

package/src/retailCommission/index.ts

@@ -21,6 +21,12 @@ export * from './enums/CommissionCountByEnum';
 export * from './enums/CommissionAggregateByEnum';
 export * from './enums/CommissionSeriesByEnum';
 export * from './enums/CommissionSimulationSkipEnum';
+export * from './enums/CommissionPayTimingEnum';
+export * from './enums/CommissionBillingPeriodEnum';
+export * from './enums/CommissionPaymentStatusEnum';
+export * from './enums/CommissionPaymentAttentionEnum';
+export * from './enums/CommissionLedgerMovementKindEnum';
+export * from './enums/CommissionPayTriggerEnum';
 
 // Entidades del dominio
 export * from './dtos/CommissionPlan';
@@ -29,6 +35,7 @@ export * from './dtos/CommissionCouponAccrual';
 export * from './dtos/CommissionCalcTrace';
 export * from './dtos/CommissionAccrual';
 export * from './dtos/CommissionPayout';
+export * from './dtos/CommissionLedger';
 
 // Contratos HTTP — uno por endpoint
 export * from './dtos/CommissionApi';

package/src/retailOrg/dtos/RetailUser.ts

@@ -4,6 +4,7 @@ import { regexIso8601 } from '../../helpers/constans/regex';
 import { CollectorSeniorityEnum } from '../enums/CollectorSeniorityEnum';
 import { EmploymentTypeEnum } from '../enums/EmploymentTypeEnum';
 import { RetailUserStatusEnum } from '../enums/RetailUserStatusEnum';
+import { RetailUserWalletLinkMethodEnum } from '../enums/RetailUserWalletLinkMethodEnum';
 
 /**
  * RetailUser — usuario retail (empleado de tienda) de un retailer (SureKeep Fase 1 — pista Retail).
@@ -74,6 +75,44 @@ export class RetailUser {
     @IsEnum(RetailUserStatusEnum)
     status!: RetailUserStatusEnum;
 
+    /** Directorio de Fiado del dueño de la wallet PCF; `null` o ausente si no tiene wallet. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    fiadoDirectoryId?: string | null;
+
+    /** Cuenta PCF de la wallet. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    pcfAccountId?: string | null;
+
+    /** Cómo se encontró la wallet: por CLABE o por teléfono. */
+    @Expose()
+    @IsOptional()
+    @IsEnum(RetailUserWalletLinkMethodEnum)
+    walletLinkMethod?: RetailUserWalletLinkMethodEnum | null;
+
+    /** Últimos 4 dígitos de la CLABE; la CLABE completa no se guarda. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(/^\d{4}$/, { message: 'walletClabeLast4 debe tener 4 dígitos' })
+    walletClabeLast4?: string | null;
+
+    /** Cuándo se vinculó (ISO). */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    @Matches(regexIso8601, { message: 'walletLinkedAt debe ser una fecha ISO 8601' })
+    walletLinkedAt?: string | null;
+
+    /** Quién la vinculó: el actorId del usuario del back office. */
+    @Expose()
+    @IsOptional()
+    @IsString()
+    walletLinkedBy?: string | null;
+
     @Expose()
     @IsString()
     @Matches(regexIso8601, { message: 'createdAt debe ser una fecha ISO 8601' })

package/src/retailOrg/dtos/requests/LinkRetailUserWalletRequest.ts

@@ -0,0 +1,24 @@
+import { Expose } from 'class-transformer';
+import { IsOptional, IsString, Matches, Validate, ValidateIf } from 'class-validator';
+import { IsSingleWalletKeyConstraint } from '../../validators/IsSingleWalletKeyConstraint';
+
+/**
+ * Body de `PUT /retailers/{retailerId}/users/{retailUserId}/wallet`: vincula la wallet PCF del
+ * vendedor por CLABE o por teléfono, exactamente uno. El servidor vuelve a resolver la cuenta.
+ */
+export class LinkRetailUserWalletRequest {
+    /** CLABE PCF, 18 dígitos. Solo se guardan los últimos 4; no va a logs completa. */
+    @Expose()
+    @ValidateIf((o: LinkRetailUserWalletRequest) => o.clabe != null || o.phone == null)
+    @Validate(IsSingleWalletKeyConstraint)
+    @IsString({ message: 'clabe debe ser texto' })
+    @Matches(/^\d{18}$/, { message: 'clabe debe tener 18 dígitos' })
+    clabe?: string | null;
+
+    /** Teléfono de México: 10 dígitos, con o sin `+52`; retail-org lo normaliza a E.164. No va a logs completo. */
+    @Expose()
+    @IsOptional()
+    @IsString({ message: 'phone debe ser texto' })
+    @Matches(/^(\+52)?\d{10}$/, { message: 'phone debe tener 10 dígitos, con o sin +52' })
+    phone?: string | null;
+}

package/src/retailOrg/dtos/requests/LookupRetailUserWalletRequest.ts

@@ -0,0 +1,24 @@
+import { Expose } from 'class-transformer';
+import { IsOptional, IsString, Matches, Validate, ValidateIf } from 'class-validator';
+import { IsSingleWalletKeyConstraint } from '../../validators/IsSingleWalletKeyConstraint';
+
+/**
+ * Body de `POST /retailers/{retailerId}/users/wallet-lookup`: busca una wallet PCF por CLABE o por
+ * teléfono, exactamente uno. No escribe nada.
+ */
+export class LookupRetailUserWalletRequest {
+    /** CLABE PCF, 18 dígitos. No va a logs completa. */
+    @Expose()
+    @ValidateIf((o: LookupRetailUserWalletRequest) => o.clabe != null || o.phone == null)
+    @Validate(IsSingleWalletKeyConstraint)
+    @IsString({ message: 'clabe debe ser texto' })
+    @Matches(/^\d{18}$/, { message: 'clabe debe tener 18 dígitos' })
+    clabe?: string | null;
+
+    /** Teléfono de México: 10 dígitos, con o sin `+52`; retail-org lo normaliza a E.164. No va a logs completo. */
+    @Expose()
+    @IsOptional()
+    @IsString({ message: 'phone debe ser texto' })
+    @Matches(/^(\+52)?\d{10}$/, { message: 'phone debe tener 10 dígitos, con o sin +52' })
+    phone?: string | null;
+}

package/src/retailOrg/dtos/responses/LookupRetailUserWalletResponse.ts

@@ -0,0 +1,11 @@
+import type { RetailUserWalletLinkMethodEnum } from '../../enums/RetailUserWalletLinkMethodEnum';
+
+/** Respuesta de `POST /retailers/{retailerId}/users/wallet-lookup`. */
+export interface LookupRetailUserWalletResponse {
+    found: boolean;
+    active: boolean;
+    /** Nombre del titular para que el administrador confirme; `null` si no se encontró. */
+    holderName: string | null;
+    /** Por dónde se buscó. */
+    method: RetailUserWalletLinkMethodEnum;
+}

package/src/retailOrg/dtos/responses/PrivateRetailUserWalletResponse.ts

@@ -0,0 +1,8 @@
+/**
+ * Respuesta de `GET /private/retailers/{retailerId}/users/{retailUserId}/wallet`: la wallet del
+ * vendedor para el motor de comisiones. Ambos `null` si no tiene wallet vinculada.
+ */
+export interface PrivateRetailUserWalletResponse {
+    directoryId: string | null;
+    pcfAccountId: string | null;
+}

package/src/retailOrg/enums/RetailUserWalletLinkMethodEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * Cómo se encontró la wallet PCF del vendedor.
+ * @enum {string}
+ *
+ * @property {string} CLABE - Por la CLABE PCF capturada en el alta.
+ * @property {string} PHONE - Por el teléfono de su usuario de Fiado.
+ */
+export enum RetailUserWalletLinkMethodEnum {
+    CLABE = 'CLABE',
+    PHONE = 'PHONE',
+}

package/src/retailOrg/index.ts

@@ -5,6 +5,7 @@ export * from './enums/StoreStatusEnum';
 export * from './enums/RetailUserStatusEnum';
 export * from './enums/EmploymentTypeEnum';
 export * from './enums/CollectorSeniorityEnum';
+export * from './enums/RetailUserWalletLinkMethodEnum';
 // F3 — Portal Admin VentasLuga (metas de venta del periodo)
 export * from './enums/GoalTargetTypeEnum';
 
@@ -26,6 +27,9 @@ export * from './dtos/validation/PrivateSellerListResponse';
 // Paginación genérica
 export * from './dtos/PaginatedResult';
 
+// Validadores
+export * from './validators/IsSingleWalletKeyConstraint';
+
 // Request DTOs (input validado por endpoint)
 export * from './dtos/requests/RetailAddressInput';
 export * from './dtos/requests/CreateRetailerRequest';
@@ -43,6 +47,8 @@ export * from './dtos/requests/ProvisionRetailUserRequest';
 export * from './dtos/requests/UpdateRetailUserRequest';
 export * from './dtos/requests/ChangeRetailUserStatusRequest';
 export * from './dtos/requests/TransferRetailUserRequest';
+export * from './dtos/requests/LookupRetailUserWalletRequest';
+export * from './dtos/requests/LinkRetailUserWalletRequest';
 // F3 — metas y KPIs del Portal Admin VL
 export * from './dtos/requests/GoalListQuery';
 export * from './dtos/requests/GoalUpsertRequest';
@@ -58,3 +64,5 @@ export * from './dtos/responses/GoalUpsertResponse';
 export * from './dtos/responses/PrivateGoalListResponse';
 export * from './dtos/responses/StoreKpiResponse';
 export * from './dtos/responses/SellerKpiResponse';
+export * from './dtos/responses/LookupRetailUserWalletResponse';
+export * from './dtos/responses/PrivateRetailUserWalletResponse';

package/src/retailOrg/validators/IsSingleWalletKeyConstraint.ts

@@ -0,0 +1,18 @@
+import {
+    ValidatorConstraint,
+    type ValidationArguments,
+    type ValidatorConstraintInterface,
+} from 'class-validator';
+
+/** Exige exactamente uno de `clabe` o `phone`. */
+@ValidatorConstraint({ name: 'isSingleWalletKey', async: false })
+export class IsSingleWalletKeyConstraint implements ValidatorConstraintInterface {
+    validate(_value: unknown, args: ValidationArguments): boolean {
+        const o = args.object as { clabe?: unknown; phone?: unknown };
+        return (o.clabe != null) !== (o.phone != null);
+    }
+
+    defaultMessage(): string {
+        return 'debe venir clabe o phone, solo uno';
+    }
+}

package/src/retailPromotions/dtos/responses/WizardSalePromotionResponses.ts

@@ -46,7 +46,10 @@ export interface ListStoreSalePromotionsResponse {
 export interface GiftOption {
     sku: string;
     name: string;
-    listPriceCents: number;
+    /** Valor del regalo: su precio de venta. */
+    valueCents?: number;
+    /** @deprecated Usa `valueCents`; trae el mismo valor. */
+    listPriceCents?: number;
     inStock: boolean;
 }
 

package/src/retailWizard/dtos/SaleLine.ts

@@ -9,7 +9,8 @@ export interface SaleLine extends WizardLinePromotionFields {
     sku: string;
     qty: number;
     basePriceCents: number;
-    listPriceCents: number | null;
+    /** @deprecated Ya no se escribe; el valor de un regalo vive en `originalPriceCents`. */
+    listPriceCents?: number | null;
     /** Llave del registro PRICE# del que salió el precio. */
     priceSk: string;
     paymentType: LinePaymentTypeEnum;

package/src/retailWizard/dtos/WizardGiftLine.ts

@@ -1,7 +1,7 @@
 import type { WizardLineRoleEnum } from '../enums/WizardLineRoleEnum';
 import type { WizardReservedLine } from './WizardReservedLine';
 
-/** Línea GIFT: ligada a un ancla, con su promo y el precio de lista que se regala. */
+/** Línea GIFT: ligada a un ancla, con su promo y el valor del regalo (su precio de venta). */
 export type WizardGiftLine = WizardReservedLine & {
     role: WizardLineRoleEnum.GIFT;
     linkedLineId: string;

package/src/retailWizard/dtos/WizardLinePromotionFields.ts

@@ -12,7 +12,7 @@ export interface WizardLinePromotionFields {
     discountCode?: string;
     /** Descuento total de la línea; neto = basePriceCents × qty − discountCents. */
     discountCents?: number;
-    /** Precio antes del descuento; en un regalo, el valor de lista con la línea a $0. */
+    /** Precio antes del descuento; en un regalo, su precio de venta con la línea a $0. */
     originalPriceCents?: number;
     /** Descuento de cada promo en la línea; sin el campo, la de `promotionId` lleva todo menos el código. */
     promotionDiscounts?: LinePromotionAmount[];

package/src/retailWizard/dtos/WizardReservedLine.ts

@@ -18,7 +18,8 @@ export interface WizardReservedLine extends WizardLinePromotionFields {
     expiresAt: string;
     /** Precio fijado de la línea (el del kit si es kit). */
     basePriceCents: number | null;
-    listPriceCents: number | null;
+    /** @deprecated Ya no se escribe; el valor de un regalo vive en `originalPriceCents`. */
+    listPriceCents?: number | null;
     /** Llave del registro PRICE# del que salió el precio. */
     priceSk: string | null;
     eligibleFinanciers: string[];

package/src/retailWizard/events/SaleCompletedV1.ts

@@ -24,7 +24,7 @@ export interface SaleCompletedV1 {
    * sin `type` un crédito con $1,300 de enganche era indistinguible de un contado de $1,300.
    */
   type?: SaleTypeEnum;
-  /** Precio de lista del equipo; en contado coincide con `amountCents`. Sin equipo se omite. */
+  /** Precio neto del equipo: su precio de venta menos su descuento. Sin equipo se omite. */
   equipmentPriceCents?: number;
   /** Enganche cobrado (solo `type=CREDIT`). */
   downPaymentCents?: number;

package/src/retailWizard/events/SaleCompletedV2.ts

@@ -31,7 +31,7 @@ export interface SaleCompletedV2 {
     imei: string | null;
     /** Lo COBRADO en caja. En contado == precio del equipo; en CREDIT es SOLO el enganche. */
     amountCents: number;
-    /** Precio de lista del equipo — la base de comisión. `null` en ventas sin el dato. */
+    /** Precio neto del equipo (venta menos descuento), la base de comisión. `null` sin el dato. */
     equipmentPriceCents: number | null;
     downPaymentCents: number | null;
     creditId: string | null;