@fiado/type-kit 3.276.0 → 3.278.0

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

@@ -0,0 +1,66 @@
+import { Expose, Type } from 'class-transformer';
+import {
+    ArrayMaxSize,
+    ArrayMinSize,
+    IsArray,
+    IsEnum,
+    IsInt,
+    IsString,
+    Matches,
+    Min,
+    ValidateNested,
+} from 'class-validator';
+import { GoalTargetTypeEnum } from '../../enums/GoalTargetTypeEnum';
+
+/** Una meta del lote. */
+export class GoalUpsertTarget {
+    /** ULID de la tienda o del vendedor. */
+    @Expose()
+    @IsString()
+    targetId!: string;
+
+    @Expose()
+    @IsEnum(GoalTargetTypeEnum)
+    targetType!: GoalTargetTypeEnum;
+
+    /**
+     * La meta MENSUAL en centavos — lo único que se guarda.
+     *
+     * 🔴 `0` NO borra: cero significa «la meta es cero» y rompe el `goalPct` con una división entre
+     * cero. Para quitar una meta está `DELETE /backoffice/goals/{periodId}/{targetType}/{targetId}`;
+     * sin fila significa «no se fijó» y la UI pinta `—`.
+     */
+    @Expose()
+    @IsInt()
+    @Min(0)
+    monthCents!: number;
+}
+
+/**
+ * Body de `PUT /backoffice/goals` — upsert POR LOTE de las metas de un periodo.
+ *
+ * ⚠️ `weekCents` y `dayCents` NO están declarados a propósito, y el manager los RECHAZA con 400 si
+ * llegan: son derivadas (`mes/4`, `mes/28`). El `@Expose()` + `excludeExtraneousValues` los
+ * descartaría en silencio, y un descarte silencioso sobre un número contra el que se le paga a la
+ * gente es peor que un error — el cliente creería que los guardó.
+ */
+export class GoalUpsertRequest {
+    /** Mes calendario `YYYY-MM`, mes acotado a 01-12. */
+    @Expose()
+    @Matches(/^\d{4}-(0[1-9]|1[0-2])$/, { message: 'periodId debe tener formato YYYY-MM (mes 01-12)' })
+    periodId!: string;
+
+    /**
+     * El lote: 1..50 metas.
+     *
+     * 🔴 El tope es 50, no 100: `TransactWriteItems` acepta 100 ítems y **cada meta consume dos** (la
+     * fila de la meta + su fila de auditoría, que va en la MISMA transacción).
+     */
+    @Expose()
+    @IsArray()
+    @ArrayMinSize(1)
+    @ArrayMaxSize(50)
+    @ValidateNested({ each: true })
+    @Type(() => GoalUpsertTarget)
+    targets!: GoalUpsertTarget[];
+}

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

@@ -0,0 +1,15 @@
+import { Expose } from 'class-transformer';
+import { IsOptional, Matches } from 'class-validator';
+
+/**
+ * Query compartido por los dos drawers de KPIs del Portal Admin VL
+ * (`GET /backoffice/stores/{storeId}/kpis` y `GET /backoffice/sellers/{sellerId}/kpis`).
+ *
+ * `periodId` es OPCIONAL: sin él se usa el mes en curso — el drawer se abre sin elegir periodo.
+ */
+export class KpiQuery {
+    @Expose()
+    @IsOptional()
+    @Matches(/^\d{4}-(0[1-9]|1[0-2])$/, { message: 'periodId debe tener formato YYYY-MM (mes 01-12)' })
+    periodId?: string;
+}

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

@@ -0,0 +1,43 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsOptional, Matches } from 'class-validator';
+import { RetailUserStatusEnum } from '../../enums/RetailUserStatusEnum';
+
+/** ULID canónico: 26 chars Crockford base32, primer char 0-7 (el timestamp cabe en 48 bits). */
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+
+/**
+ * Query de `GET /private/sellers` — el padrón de una cadena, M2M.
+ *
+ * 🔴 Acá el `retailerId` **viene en el request**, al revés que en los `/backoffice/` (donde se impone
+ * desde el token). Es el modelo M2M de la casa: el endpoint es VPC-only y su seguridad es de RED, no
+ * de identidad. Cualquier lambda dentro de la VPC puede pedir cualquier retailer — decisión
+ * consciente, no un descuido.
+ */
+export class PrivateSellerListQuery {
+    @Expose()
+    @Matches(ULID, { message: 'retailerId debe ser un ULID' })
+    retailerId!: string;
+
+    /**
+     * ⚠️ **Sin `status` vienen TODOS los estados, no solo los activos.**
+     *
+     * El diseño original proponía default `ACTIVE`, pero con este enum eso deja al motor de comisiones
+     * sin ninguna forma de pedir el padrón completo — y un vendedor dado de baja el día 20 sí tiene
+     * comisión por lo que vendió hasta el 19. Filtrar por default sería perderlo en silencio.
+     */
+    @Expose()
+    @IsOptional()
+    @IsEnum(RetailUserStatusEnum)
+    status?: RetailUserStatusEnum;
+
+    /**
+     * Quién llama. `Feature.ANONIMUS` no trae actor, y este endpoint exporta la nómina completa de una
+     * cadena: sin esto el registro de acceso a PII quedaría sin nadie a quien atribuírselo. Lo llena el
+     * publisher de `@fiado/api-invoker`; si falta, el lambda registra `m2m:unknown` y loguea un WARN —
+     * nunca omite el registro.
+     */
+    @Expose()
+    @IsOptional()
+    @Matches(/^[a-z0-9-]{1,64}$/, { message: 'callerService debe ser el nombre del lambda (kebab-case)' })
+    callerService?: string;
+}

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

@@ -0,0 +1,20 @@
+import type { GoalAmounts } from '../GoalAmounts';
+import type { GoalTargetTypeEnum } from '../../enums/GoalTargetTypeEnum';
+
+/** Una meta del periodo, con las tres cifras ya derivadas. */
+export interface GoalDto extends GoalAmounts {
+    targetId: string;
+    targetType: GoalTargetTypeEnum;
+}
+
+/**
+ * Respuesta de `GET /backoffice/goals`.
+ *
+ * ⚠️ Un periodo sin metas devuelve `goals: []`, **no un 404**: que no se hayan fijado es un estado
+ * válido del negocio, no una ruta que no existe. Y una meta borrada simplemente no viene en la
+ * lista — no hay estado «borrada», la fila deja de existir.
+ */
+export interface GoalListResponse {
+    periodId: string;
+    goals: GoalDto[];
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Respuesta de `PUT /backoffice/goals` — cuántas metas quedaron escritas.
+ *
+ * `updated` siempre iguala `targets.length` del request: el lote es todo-o-nada (una sola
+ * `TransactWriteItems`). Nunca hay un lote parcial que explicar.
+ */
+export interface GoalUpsertResponse {
+    periodId: string;
+    updated: number;
+}

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

@@ -0,0 +1,29 @@
+import type { GoalAmounts } from '../GoalAmounts';
+import type { SoldAggregate } from './StoreKpiResponse';
+
+/** La tienda de casa del vendedor, resuelta para el drawer. */
+export interface SellerStoreRef {
+    storeId: string;
+    name: string;
+    zoneId: string | null;
+}
+
+/**
+ * Respuesta de `GET /backoffice/sellers/{sellerId}/kpis` — el drawer de un vendedor.
+ *
+ * ⚠️ `store` es la tienda de CASA (`homeStoreId`), no la única donde puede vender: `RetailUser_GT`
+ * también lleva `coverageStoreIds`. El agregado del lake **no filtra por tienda** — si un vendedor
+ * de la Tienda A cubrió un turno en la B, esa venta cuenta en su avance. Es lo correcto: la cuota es
+ * suya, no de la tienda. Se deja escrito porque es justo el tipo de cosa que después parece un bug.
+ *
+ * Misma regla que el gemelo de tiendas: `null`, nunca `0`.
+ */
+export interface SellerKpiResponse {
+    sellerId: string;
+    displayName: string | null;
+    /** `null` si el vendedor no tiene `homeStoreId`, o si esa tienda ya no existe. */
+    store: SellerStoreRef | null;
+    goal: GoalAmounts | null;
+    sold: SoldAggregate | null;
+    goalPct: number | null;
+}

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

@@ -0,0 +1,36 @@
+import type { GoalAmounts } from '../GoalAmounts';
+
+/**
+ * Volumen vendido en el periodo, según el data lake.
+ *
+ * 🔴 `soldCents` NO es `amountCents` de la venta. Es `COALESCE(equipmentPriceCents, amountCents)` —
+ * volumen **colocado**, por DEC-032. En una venta a crédito `amountCents` es solo el enganche: un
+ * equipo de $5,000 financiado aportaría $1,300 y el vendedor cobraría comisión sobre eso.
+ */
+export interface SoldAggregate {
+    pieces: number;
+    soldCents: number;
+}
+
+/**
+ * Respuesta de `GET /backoffice/stores/{storeId}/kpis` — el drawer de una tienda.
+ *
+ * 🔴 **`null`, nunca `0`.** Un `0` dice *«no vendió»*; un `null` dice *«no sé todavía»*, y la UI lo
+ * pinta `—`. Un 0 % de meta a media tarde manda a alguien a corregir algo que nadie fijó.
+ *
+ * `sellersActive` es la excepción: sale del padrón (`RetailUser_GT`), siempre se puede contar, y `0`
+ * ahí SÍ es un dato — una tienda sin vendedores asignados.
+ */
+export interface StoreKpiResponse {
+    storeId: string;
+    name: string;
+    zoneId: string | null;
+    /** Vendedores ACTIVE con esta tienda como `homeStoreId`. `0` es válido. */
+    sellersActive: number;
+    /** `null` si no se fijó meta para el periodo. */
+    goal: GoalAmounts | null;
+    /** `null` si el lake no contestó (o si está apagado por flag). NUNCA ceros. */
+    sold: SoldAggregate | null;
+    /** Avance sobre la meta mensual, 1 decimal. `null` si falta cualquiera de los dos. */
+    goalPct: number | null;
+}

package/src/retailOrg/dtos/validation/PrivateSellerListResponse.ts

@@ -0,0 +1,32 @@
+import type { RetailUserStatusEnum } from '../../enums/RetailUserStatusEnum';
+
+/**
+ * Shape mínimo de un vendedor para el motor de comisiones (F3b): a quién pagarle, de qué tienda es y
+ * en qué tier va.
+ *
+ * **Sin PII** — nada de teléfono ni `cognitoSub`. `displayName` es el rótulo de conveniencia con el
+ * que el motor arma su reporte de devengo; no es identidad (la identidad vive en RBAC).
+ *
+ * `commissionTier` no es adorno: es lo que el motor usa para resolver CUÁNTO le toca a cada vendedor
+ * según el plan de comisiones vigente.
+ */
+export interface PrivateSellerDto {
+    sellerId: string;
+    displayName: string | null;
+    homeStoreId: string | null;
+    commissionTier: string;
+    status: RetailUserStatusEnum;
+}
+
+/**
+ * Respuesta de `GET /private/sellers?retailerId=…` — el padrón de una cadena, para máquinas.
+ *
+ * ⚠️ `status` viene en cada fila a propósito. Un vendedor dado de baja a mitad de periodo **sí tiene
+ * comisión** por lo que vendió antes, así que el filtro `?status=` es una conveniencia y el motor de
+ * comisiones probablemente tenga que pedir TODOS. Pedir solo activos y perder a alguien que renunció
+ * el día 20 sería un error caro.
+ */
+export interface PrivateSellerListResponse {
+    retailerId: string;
+    sellers: PrivateSellerDto[];
+}

package/src/retailOrg/enums/GoalTargetTypeEnum.ts

@@ -0,0 +1,11 @@
+/**
+ * A quién se le fija una meta de venta del periodo (SureKeep F3, Portal Admin VentasLuga).
+ *
+ * Es parte de la SORT KEY de `RetailGoal_GT` (`GOAL#<periodId>#<targetType>#<targetId>`), así que
+ * los valores son contrato de datos, no solo de API: cambiar un literal deja huérfanas las filas ya
+ * escritas. Solo hay dos targets y no se prevén más — la meta de una zona sale de sumar sus tiendas.
+ */
+export enum GoalTargetTypeEnum {
+    STORE = 'STORE',
+    SELLER = 'SELLER',
+}

package/src/retailOrg/index.ts

@@ -5,9 +5,12 @@ export * from './enums/StoreStatusEnum';
 export * from './enums/RetailUserStatusEnum';
 export * from './enums/EmploymentTypeEnum';
 export * from './enums/CollectorSeniorityEnum';
+// F3 — Portal Admin VentasLuga (metas de venta del periodo)
+export * from './enums/GoalTargetTypeEnum';
 
 // Entity DTOs
 export * from './dtos/GeoLocation';
+export * from './dtos/GoalAmounts';
 export * from './dtos/Retailer';
 export * from './dtos/Zone';
 export * from './dtos/Store';
@@ -18,6 +21,7 @@ export * from './dtos/validation/RetailerValidationDto';
 export * from './dtos/validation/StoreValidationDto';
 export * from './dtos/validation/RetailUserValidationDto';
 export * from './dtos/validation/CollectorValidationDto';
+export * from './dtos/validation/PrivateSellerListResponse';
 
 // Paginación genérica
 export * from './dtos/PaginatedResult';
@@ -39,6 +43,16 @@ export * from './dtos/requests/ProvisionRetailUserRequest';
 export * from './dtos/requests/UpdateRetailUserRequest';
 export * from './dtos/requests/ChangeRetailUserStatusRequest';
 export * from './dtos/requests/TransferRetailUserRequest';
+// F3 — metas y KPIs del Portal Admin VL
+export * from './dtos/requests/GoalListQuery';
+export * from './dtos/requests/GoalUpsertRequest';
+export * from './dtos/requests/GoalPathParams';
+export * from './dtos/requests/KpiQuery';
+export * from './dtos/requests/PrivateSellerListQuery';
 
 // Response DTOs
 export * from './dtos/responses/RetailerHierarchyResponse';
+export * from './dtos/responses/GoalListResponse';
+export * from './dtos/responses/GoalUpsertResponse';
+export * from './dtos/responses/StoreKpiResponse';
+export * from './dtos/responses/SellerKpiResponse';

package/bin/loanCredit/dtos/requests/UpdateActivationChecklistRequest.d.ts

@@ -1,11 +0,0 @@
-/**
- * Body de PUT /credits/:creditId/checklist (loan-credit-business). Marca condiciones de activación
- * cumplidas. Solo se mandan las que cambian; en F3 las marcarán los flujos de firma de contrato
- * (`downPayment` + `contractSigned`) y de enrolamiento MDM (`imeiEnrolled` + `lockVerified`).
- */
-export declare class UpdateActivationChecklistRequest {
-    downPayment?: boolean;
-    contractSigned?: boolean;
-    imeiEnrolled?: boolean;
-    lockVerified?: boolean;
-}

package/bin/loanCredit/dtos/requests/UpdateActivationChecklistRequest.js

@@ -1,46 +0,0 @@
-"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.UpdateActivationChecklistRequest = void 0;
-const class_transformer_1 = require("class-transformer");
-const class_validator_1 = require("class-validator");
-/**
- * Body de PUT /credits/:creditId/checklist (loan-credit-business). Marca condiciones de activación
- * cumplidas. Solo se mandan las que cambian; en F3 las marcarán los flujos de firma de contrato
- * (`downPayment` + `contractSigned`) y de enrolamiento MDM (`imeiEnrolled` + `lockVerified`).
- */
-class UpdateActivationChecklistRequest {
-}
-exports.UpdateActivationChecklistRequest = UpdateActivationChecklistRequest;
-__decorate([
-    (0, class_transformer_1.Expose)(),
-    (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsBoolean)(),
-    __metadata("design:type", Boolean)
-], UpdateActivationChecklistRequest.prototype, "downPayment", void 0);
-__decorate([
-    (0, class_transformer_1.Expose)(),
-    (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsBoolean)(),
-    __metadata("design:type", Boolean)
-], UpdateActivationChecklistRequest.prototype, "contractSigned", void 0);
-__decorate([
-    (0, class_transformer_1.Expose)(),
-    (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsBoolean)(),
-    __metadata("design:type", Boolean)
-], UpdateActivationChecklistRequest.prototype, "imeiEnrolled", void 0);
-__decorate([
-    (0, class_transformer_1.Expose)(),
-    (0, class_validator_1.IsOptional)(),
-    (0, class_validator_1.IsBoolean)(),
-    __metadata("design:type", Boolean)
-], UpdateActivationChecklistRequest.prototype, "lockVerified", void 0);

package/bin/loanCredit/enums/ClientLevelEnum.d.ts

@@ -1,11 +0,0 @@
-/**
- * Nivel del cliente según su SCI (M7/05_MOTOR §3.2): 21-60 Bronce · 61-80 Plata · 81-100 Oro.
- * Distinto de `CreditPlanLevelEnum` de loanOfferings (que además tiene `ALL` para planes):
- * un CLIENTE nunca es `ALL`.
- * @enum {string}
- */
-export declare enum ClientLevelEnum {
-    BRONZE = "BRONZE",
-    SILVER = "SILVER",
-    GOLD = "GOLD"
-}

package/bin/loanCredit/enums/ClientLevelEnum.js

@@ -1,15 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.ClientLevelEnum = void 0;
-/**
- * Nivel del cliente según su SCI (M7/05_MOTOR §3.2): 21-60 Bronce · 61-80 Plata · 81-100 Oro.
- * Distinto de `CreditPlanLevelEnum` de loanOfferings (que además tiene `ALL` para planes):
- * un CLIENTE nunca es `ALL`.
- * @enum {string}
- */
-var ClientLevelEnum;
-(function (ClientLevelEnum) {
-    ClientLevelEnum["BRONZE"] = "BRONZE";
-    ClientLevelEnum["SILVER"] = "SILVER";
-    ClientLevelEnum["GOLD"] = "GOLD";
-})(ClientLevelEnum || (exports.ClientLevelEnum = ClientLevelEnum = {}));