@fiado/type-kit 3.275.0 → 3.277.0

package/bin/retailOrg/dtos/responses/SellerKpiResponse.d.ts

@@ -0,0 +1,27 @@
+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/bin/retailOrg/dtos/responses/SellerKpiResponse.js

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

package/bin/retailOrg/dtos/responses/StoreKpiResponse.d.ts

@@ -0,0 +1,34 @@
+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/bin/retailOrg/dtos/responses/StoreKpiResponse.js

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

package/bin/retailOrg/dtos/validation/PrivateSellerListResponse.d.ts

@@ -0,0 +1,30 @@
+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/bin/retailOrg/dtos/validation/PrivateSellerListResponse.js

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

package/bin/retailOrg/enums/GoalTargetTypeEnum.d.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 declare enum GoalTargetTypeEnum {
+    STORE = "STORE",
+    SELLER = "SELLER"
+}

package/bin/retailOrg/enums/GoalTargetTypeEnum.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GoalTargetTypeEnum = void 0;
+/**
+ * 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.
+ */
+var GoalTargetTypeEnum;
+(function (GoalTargetTypeEnum) {
+    GoalTargetTypeEnum["STORE"] = "STORE";
+    GoalTargetTypeEnum["SELLER"] = "SELLER";
+})(GoalTargetTypeEnum || (exports.GoalTargetTypeEnum = GoalTargetTypeEnum = {}));

package/bin/retailOrg/index.d.ts

@@ -5,7 +5,9 @@ export * from './enums/StoreStatusEnum';
 export * from './enums/RetailUserStatusEnum';
 export * from './enums/EmploymentTypeEnum';
 export * from './enums/CollectorSeniorityEnum';
+export * from './enums/GoalTargetTypeEnum';
 export * from './dtos/GeoLocation';
+export * from './dtos/GoalAmounts';
 export * from './dtos/Retailer';
 export * from './dtos/Zone';
 export * from './dtos/Store';
@@ -14,6 +16,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';
 export * from './dtos/PaginatedResult';
 export * from './dtos/requests/RetailAddressInput';
 export * from './dtos/requests/CreateRetailerRequest';
@@ -31,4 +34,13 @@ export * from './dtos/requests/ProvisionRetailUserRequest';
 export * from './dtos/requests/UpdateRetailUserRequest';
 export * from './dtos/requests/ChangeRetailUserStatusRequest';
 export * from './dtos/requests/TransferRetailUserRequest';
+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';
 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/retailOrg/index.js

@@ -21,8 +21,11 @@ __exportStar(require("./enums/StoreStatusEnum"), exports);
 __exportStar(require("./enums/RetailUserStatusEnum"), exports);
 __exportStar(require("./enums/EmploymentTypeEnum"), exports);
 __exportStar(require("./enums/CollectorSeniorityEnum"), exports);
+// F3 — Portal Admin VentasLuga (metas de venta del periodo)
+__exportStar(require("./enums/GoalTargetTypeEnum"), exports);
 // Entity DTOs
 __exportStar(require("./dtos/GeoLocation"), exports);
+__exportStar(require("./dtos/GoalAmounts"), exports);
 __exportStar(require("./dtos/Retailer"), exports);
 __exportStar(require("./dtos/Zone"), exports);
 __exportStar(require("./dtos/Store"), exports);
@@ -32,6 +35,7 @@ __exportStar(require("./dtos/validation/RetailerValidationDto"), exports);
 __exportStar(require("./dtos/validation/StoreValidationDto"), exports);
 __exportStar(require("./dtos/validation/RetailUserValidationDto"), exports);
 __exportStar(require("./dtos/validation/CollectorValidationDto"), exports);
+__exportStar(require("./dtos/validation/PrivateSellerListResponse"), exports);
 // Paginación genérica
 __exportStar(require("./dtos/PaginatedResult"), exports);
 // Request DTOs (input validado por endpoint)
@@ -51,5 +55,15 @@ __exportStar(require("./dtos/requests/ProvisionRetailUserRequest"), exports);
 __exportStar(require("./dtos/requests/UpdateRetailUserRequest"), exports);
 __exportStar(require("./dtos/requests/ChangeRetailUserStatusRequest"), exports);
 __exportStar(require("./dtos/requests/TransferRetailUserRequest"), exports);
+// F3 — metas y KPIs del Portal Admin VL
+__exportStar(require("./dtos/requests/GoalListQuery"), exports);
+__exportStar(require("./dtos/requests/GoalUpsertRequest"), exports);
+__exportStar(require("./dtos/requests/GoalPathParams"), exports);
+__exportStar(require("./dtos/requests/KpiQuery"), exports);
+__exportStar(require("./dtos/requests/PrivateSellerListQuery"), exports);
 // Response DTOs
 __exportStar(require("./dtos/responses/RetailerHierarchyResponse"), exports);
+__exportStar(require("./dtos/responses/GoalListResponse"), exports);
+__exportStar(require("./dtos/responses/GoalUpsertResponse"), exports);
+__exportStar(require("./dtos/responses/StoreKpiResponse"), exports);
+__exportStar(require("./dtos/responses/SellerKpiResponse"), exports);

package/package.json

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

package/src/biometrics/dtos/BiometricDelivery.ts

@@ -30,6 +30,45 @@ export class RedirectDelivery {
     expiresAt!: string;
 }
 
+/**
+ * `deliveryMode = EMBEDDED_SDK`. El caller monta el SDK del proveedor **en su propia pantalla** con
+ * estos parámetros, en vez de mandar al usuario a un link hospedado.
+ *
+ * Para qué: hay flujos donde el usuario está PRESENTE frente a un dispositivo que no es el suyo —el
+ * vendedor le pasa la tablet de la tienda— y sacarlo a un navegador externo rompe la atención.
+ * Mismo biométrico y mismo veredicto que `REDIRECT`; lo único distinto es dónde corre.
+ *
+ * ⚠️ **Ninguno de los tres campos es secreto.** El `clientId` y el `flowId` viajan al navegador como
+ * parámetros del widget y se leen en el inspector; el `metadata` lo devuelve el proveedor tal cual
+ * en cada webhook. Lo que SÍ es secreto —el Client Secret con el que se firma el
+ * `userPhotoLinkHash`— nunca sale de `metamap-connector` y no viaja acá.
+ */
+export class EmbeddedSdkDelivery {
+    /** `merchantToken` del proveedor. Público: viaja al navegador. */
+    @Expose() @IsString() @IsNotEmpty()
+    clientId!: string;
+
+    /** El flow del proveedor a ejecutar. Sale del catálogo, no de una env var del caller. */
+    @Expose() @IsString() @IsNotEmpty()
+    flowId!: string;
+
+    /**
+     * El `metadata` ya serializado, **listo para pasárselo al SDK tal cual**.
+     *
+     * 🔴 Es un JSON string, NO un objeto y NO base64. El proveedor lo devuelve literal en cada
+     * webhook y es el único canal de correlación que existe. Si el caller lo re-serializa o lo
+     * codifica, el `userPhotoLink` que el proveedor reconstruye deja de ser idéntico al que se
+     * firmó, el hash del facematch no cuadra, y rechaza la verificación con «Invalid hash or url»
+     * DESPUÉS de que el usuario ya se tomó la selfie. Pasarlo sin tocarlo.
+     */
+    @Expose() @IsString() @IsNotEmpty()
+    metadata!: string;
+
+    /** Hasta cuándo sirven estos parámetros. ISO-8601 UTC con `Z`. */
+    @Expose() @IsISO8601({ strict: true })
+    expiresAt!: string;
+}
+
 /**
  * `deliveryMode = CHALLENGE`. El biométrico corre en el dispositivo (Apple Face ID, biometría de
  * Android) y el cliente devuelve una attestation firmada.
@@ -72,10 +111,15 @@ export class ImmediateDelivery {
  *
  * ```ts
  * switch (res.deliveryMode) {
- *   case BiometricDeliveryModeEnum.REDIRECT:  abrir((res.delivery as RedirectDelivery).link); break;
- *   case BiometricDeliveryModeEnum.CHALLENGE: firmar(res.delivery as ChallengeDelivery); break;
- *   case BiometricDeliveryModeEnum.IMMEDIATE: leer(res.result); break;
+ *   case BiometricDeliveryModeEnum.REDIRECT:     abrir((res.delivery as RedirectDelivery).link); break;
+ *   case BiometricDeliveryModeEnum.EMBEDDED_SDK: montarSdk(res.delivery as EmbeddedSdkDelivery); break;
+ *   case BiometricDeliveryModeEnum.CHALLENGE:    firmar(res.delivery as ChallengeDelivery); break;
+ *   case BiometricDeliveryModeEnum.IMMEDIATE:    leer(res.result); break;
  * }
  * ```
  */
-export type BiometricDelivery = RedirectDelivery | ChallengeDelivery | ImmediateDelivery;
+export type BiometricDelivery =
+    | RedirectDelivery
+    | EmbeddedSdkDelivery
+    | ChallengeDelivery
+    | ImmediateDelivery;

package/src/biometrics/dtos/requests/CreateBiometricVerificationRequest.ts

@@ -10,6 +10,7 @@ import {
     Min,
     ValidateNested,
 } from 'class-validator';
+import { BiometricDeliveryModeEnum } from '../../enums/BiometricDeliveryModeEnum';
 import { BiometricProviderEnum } from '../../enums/BiometricProviderEnum';
 import { BiometricTypeEnum } from '../../enums/BiometricTypeEnum';
 import { BiometricSubject } from '../BiometricSubject';
@@ -98,4 +99,23 @@ export class CreateBiometricVerificationRequest {
      */
     @Expose() @IsOptional() @IsString() @MaxLength(256)
     callerContext?: string;
+
+    /**
+     * CÓMO quieres recibir lo que hace falta para ejecutar el biométrico. Default `REDIRECT`.
+     *
+     * Es una **preferencia, no una orden**: el servicio responde con el modo que el proveedor
+     * elegido soporta de verdad, y el modo real siempre viene en `deliveryMode` de la respuesta.
+     * Nunca asumas que te tocó el que pediste — discrimina por el de la respuesta.
+     *
+     * Con `METAMAP` hoy:
+     * - `REDIRECT` → link hospedado y acortado. Para mandárselo al usuario a SU dispositivo.
+     * - `EMBEDDED_SDK` → los parámetros para montar el widget en TU pantalla. Para cuando el
+     *   usuario está presente frente a un dispositivo que no es el suyo.
+     *
+     * Pedir un modo que el proveedor no soporta responde `422 DELIVERY_MODE_NOT_SUPPORTED` — no se
+     * degrada en silencio al default, porque el caller que pidió SDK y recibe un link no tiene
+     * dónde montarlo y se entera hasta que la pantalla queda en blanco.
+     */
+    @Expose() @IsOptional() @IsEnum(BiometricDeliveryModeEnum)
+    deliveryMode?: BiometricDeliveryModeEnum;
 }

package/src/biometrics/enums/BiometricDeliveryModeEnum.ts

@@ -17,12 +17,26 @@
  *
  * El `GET` de polling NO cambia entre modos: devuelve estado, no mecanismo.
  *
- * `biometrics-business` — Entrega 1 (solo `REDIRECT` produce valores reales).
+ * `biometrics-business` — Entrega 1: `REDIRECT` y `EMBEDDED_SDK` producen valores reales.
  */
 export enum BiometricDeliveryModeEnum {
     /** `delivery` trae `{ link, expiresAt }`. El usuario abre el link y ejecuta ahí. */
     REDIRECT = 'REDIRECT',
 
+    /**
+     * `delivery` trae `{ clientId, flowId, metadata, expiresAt }`. El caller monta el SDK del
+     * proveedor **en su propia pantalla** con esos parámetros, en vez de mandar al usuario a un
+     * link hospedado.
+     *
+     * Existe porque hay flujos donde el usuario está PRESENTE frente a un dispositivo que no es el
+     * suyo — el vendedor le pasa la tablet de la tienda — y sacarlo a un navegador externo rompe la
+     * atención. Mismo biométrico, mismo veredicto, distinta superficie.
+     *
+     * Es exactamente lo que hoy arma a mano `retail-wizard-business` para su modalidad
+     * `STORE_DEVICE`; este modo existe para que deje de armarlo.
+     */
+    EMBEDDED_SDK = 'EMBEDDED_SDK',
+
     /** `delivery` trae `{ challenge, nonce, expiresAt }`. El dispositivo firma y devuelve. */
     CHALLENGE = 'CHALLENGE',
 

package/src/helpdesk/dtos/ZendeskInternalAlertRequest.ts

@@ -1,4 +1,4 @@
-import { IsEnum, IsNotEmpty, IsOptional, IsString } from "class-validator";
+import { ArrayNotEmpty, IsArray, IsEnum, IsNotEmpty, IsOptional, IsString } from "class-validator";
 import { InternalAlertChannel } from "../enums/InternalAlertChannelEnum";
 
 /**
@@ -20,9 +20,17 @@ export class ZendeskInternalAlertRequest {
     @IsString()
     note: string;
 
-    /** Decide el ruteo en Zendesk (tag, vista y equipo). */
-    @IsEnum(InternalAlertChannel)
-    channel: InternalAlertChannel;
+    /**
+     * Equipos que deben ver la alerta. Un mismo hecho puede requerir a los dos: por ejemplo un
+     * status de verificación que Compliance evalúa y el equipo interno corrige.
+     *
+     * Los hilos se agrupan por combinación exacta: una alerta `[COMPLIANCE]` no cae en el ticket
+     * de `[INTERNAL, COMPLIANCE]`, para que restringir un canal por rol siga siendo posible.
+     */
+    @IsArray()
+    @ArrayNotEmpty()
+    @IsEnum(InternalAlertChannel, { each: true })
+    channels: InternalAlertChannel[];
 
     /** Id del evento origen, para rastrear la alerta de vuelta. */
     @IsString()

package/src/retailOrg/dtos/GoalAmounts.ts

@@ -0,0 +1,18 @@
+/**
+ * Las tres cifras de una meta — y las tres salen de UNA SOLA captura.
+ *
+ * 🔴 Solo `monthCents` se guarda. `weekCents` (`mes/4`) y `dayCents` (`mes/28`) las DERIVA el backend
+ * en cada lectura, y por eso `PUT /backoffice/goals` las RECHAZA si vienen en el request: aceptarlas
+ * del cliente abre la puerta a que lleguen desincronizadas entre sí y a que dos pantallas midan el
+ * mismo avance contra números distintos.
+ *
+ * Se devuelven ya calculadas para que ninguna pantalla repita la división.
+ */
+export interface GoalAmounts {
+    /** La meta mensual en centavos — lo único persistido. */
+    monthCents: number;
+    /** Derivada: `monthCents / 4`, redondeada. */
+    weekCents: number;
+    /** Derivada: `monthCents / 28`, redondeada. */
+    dayCents: number;
+}

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

@@ -0,0 +1,25 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsOptional, Matches } from 'class-validator';
+import { GoalTargetTypeEnum } from '../../enums/GoalTargetTypeEnum';
+
+/**
+ * Query de `GET /backoffice/goals` — las metas de un periodo.
+ *
+ * ⚠️ `retailerId` NO es parámetro: sale del token (D10). Un `?retailerId=` en el request se ignora a
+ * propósito — aceptarlo dejaría que un Admin VL mire las metas de la cadena de al lado.
+ */
+export class GoalListQuery {
+    /**
+     * Mes calendario `YYYY-MM`. El regex acota el mes a 01-12: `\d{2}` a secas aceptaría `2026-13`,
+     * que escribiría una partición que ninguna consulta vuelve a encontrar.
+     */
+    @Expose()
+    @Matches(/^\d{4}-(0[1-9]|1[0-2])$/, { message: 'periodId debe tener formato YYYY-MM (mes 01-12)' })
+    periodId!: string;
+
+    /** Si falta, devuelve los dos tipos — el `begins_with` del periodo ya los trae juntos. */
+    @Expose()
+    @IsOptional()
+    @IsEnum(GoalTargetTypeEnum)
+    targetType?: GoalTargetTypeEnum;
+}

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

@@ -0,0 +1,25 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsString, Matches } from 'class-validator';
+import { GoalTargetTypeEnum } from '../../enums/GoalTargetTypeEnum';
+
+/**
+ * Path params de `DELETE /backoffice/goals/{periodId}/{targetType}/{targetId}`.
+ *
+ * Una meta NO tiene id propio: se identifica por la terna *(periodo, tipo, target)*, que es
+ * exactamente su sort key. Por eso los tres van en el path y por eso hay un DTO para validarlos —
+ * un `targetType` fuera del enum arma una sk que nunca matchea y devolvería un 404 mentiroso en vez
+ * del 400 que corresponde.
+ */
+export class GoalPathParams {
+    @Expose()
+    @Matches(/^\d{4}-(0[1-9]|1[0-2])$/, { message: 'periodId debe tener formato YYYY-MM (mes 01-12)' })
+    periodId!: string;
+
+    @Expose()
+    @IsEnum(GoalTargetTypeEnum)
+    targetType!: GoalTargetTypeEnum;
+
+    @Expose()
+    @IsString()
+    targetId!: string;
+}

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