@fiado/type-kit 3.505.0 → 3.506.0

package/_test_/unit/retailCommission/latestClosedPayout.test.ts

@@ -0,0 +1,29 @@
+import 'reflect-metadata';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import {
+  PrivateLatestClosedPayoutQuery,
+  type PrivateLatestClosedPayoutResponse,
+} from '../../../src/retailCommission';
+
+describe('PrivateLatestClosedPayoutQuery', () => {
+  const errorsOf = (payload: object) =>
+    validateSync(plainToInstance(PrivateLatestClosedPayoutQuery, payload, { excludeExtraneousValues: true })).map(
+      (e) => e.property,
+    );
+
+  it('acepta un retailerId', () => expect(errorsOf({ retailerId: 'r-1' })).toEqual([]));
+  it('exige el retailerId', () => expect(errorsOf({})).toContain('retailerId'));
+});
+
+describe('PrivateLatestClosedPayoutResponse', () => {
+  it('sin corte cerrado el periodo viaja en null', () => {
+    const empty: PrivateLatestClosedPayoutResponse = { retailerId: 'r-1', period: null, sellers: [] };
+    const closed: PrivateLatestClosedPayoutResponse = {
+      retailerId: 'r-1',
+      period: { periodId: '2026-09-28', from: '2026-09-28', to: '2026-10-04' },
+      sellers: [{ retailUserId: 'u-1', amountCents: 12000 }],
+    };
+    expect([empty.period, closed.sellers[0].amountCents]).toEqual([null, 12000]);
+  });
+});

package/_test_/unit/retailOrg/dtos/sellerTableSources.test.ts

@@ -0,0 +1,62 @@
+import 'reflect-metadata';
+import { plainToInstance, type ClassConstructor } from 'class-transformer';
+import { validateSync } from 'class-validator';
+import {
+  GoalTargetTypeEnum,
+  PrivateGoalListQuery,
+  PrivateSellerListQuery,
+  type PrivateGoalListResponse,
+  type PrivateSellerDto,
+  type StoreValidationDto,
+} from '../../../../src/retailOrg';
+
+const RETAILER = '01J9ZQ0000000000000000000A';
+
+function errorsOf<T extends object>(cls: ClassConstructor<T>, payload: object): string[] {
+  return validateSync(plainToInstance(cls, payload, { excludeExtraneousValues: true }) as object).map(
+    (e) => e.property,
+  );
+}
+
+describe('PrivateGoalListQuery', () => {
+  it('acepta retailer, periodo y tipo', () =>
+    expect(errorsOf(PrivateGoalListQuery, { retailerId: RETAILER, periodId: '2026-10', targetType: 'SELLER' })).toEqual([]));
+  it('acepta sin tipo', () => expect(errorsOf(PrivateGoalListQuery, { retailerId: RETAILER, periodId: '2026-10' })).toEqual([]));
+  it('rechaza un retailerId que no es ULID', () =>
+    expect(errorsOf(PrivateGoalListQuery, { retailerId: 'x', periodId: '2026-10' })).toContain('retailerId'));
+  it('rechaza el mes 13', () =>
+    expect(errorsOf(PrivateGoalListQuery, { retailerId: RETAILER, periodId: '2026-13' })).toContain('periodId'));
+  it('rechaza un tipo fuera del catálogo', () =>
+    expect(errorsOf(PrivateGoalListQuery, { retailerId: RETAILER, periodId: '2026-10', targetType: 'ZONE' })).toContain(
+      'targetType',
+    ));
+});
+
+describe('PrivateSellerListQuery.includePhone', () => {
+  it('lee "true" como verdadero', () => {
+    const q = plainToInstance(PrivateSellerListQuery, { retailerId: RETAILER, includePhone: 'true' }, { excludeExtraneousValues: true });
+    expect(q.includePhone).toBe(true);
+    expect(validateSync(q)).toEqual([]);
+  });
+  it('sin el parámetro queda en falso', () => {
+    const q = plainToInstance(PrivateSellerListQuery, { retailerId: RETAILER }, { excludeExtraneousValues: true });
+    expect(q.includePhone).toBe(false);
+  });
+});
+
+describe('shapes de los privados del padrón', () => {
+  it('la tienda publica a su encargado y el vendedor su teléfono opcional', () => {
+    const store: StoreValidationDto = {
+      storeId: 's', retailerId: RETAILER, zoneId: null, zoneName: null, code: 'C', name: 'N', status: 'ACTIVE' as never,
+      managerRetailUserId: 'u-1',
+    };
+    const seller: PrivateSellerDto = {
+      sellerId: 'u-1', displayName: null, homeStoreId: 's', commissionTier: 'seller', status: 'ACTIVE' as never, phone: null,
+    };
+    const goals: PrivateGoalListResponse = {
+      retailerId: RETAILER, periodId: '2026-10',
+      goals: [{ targetId: 'u-1', targetType: GoalTargetTypeEnum.SELLER, monthCents: 3000, weekCents: 750, dayCents: 107 }],
+    };
+    expect([store.managerRetailUserId, seller.phone, goals.goals.length]).toEqual(['u-1', null, 1]);
+  });
+});

package/_test_/unit/retailWizard/sellerTableShapes.test.ts

@@ -0,0 +1,43 @@
+import 'reflect-metadata';
+import {
+  SellerTableSourceStatusEnum,
+  type BackofficeSellerTableResponse,
+} from '../../../src/retailWizard';
+
+describe('BackofficeSellerTableResponse', () => {
+  it('declara las tres fuentes y una fila completa', () => {
+    const response: BackofficeSellerTableResponse = {
+      from: '2026-09-07T06:00:00.000Z',
+      to: '2026-10-07T05:59:59.999Z',
+      truncated: false,
+      sources: {
+        roster: SellerTableSourceStatusEnum.OK,
+        goals: SellerTableSourceStatusEnum.UNAVAILABLE,
+        commission: SellerTableSourceStatusEnum.OK,
+      },
+      commissionPeriod: { periodId: '2026-09-28', from: '2026-09-28', to: '2026-10-04' },
+      items: [
+        {
+          retailUserId: 'u-1',
+          name: 'Ana',
+          status: 'ACTIVE' as never,
+          phone: null,
+          storeId: null,
+          storeName: null,
+          zoneName: null,
+          isStoreAdmin: false,
+          salesCount: 0,
+          placedCents: 0,
+          averageTicketCents: null,
+          lastSaleAt: null,
+          weekOverWeekChangePct: null,
+          goalCents: null,
+          commissionCents: null,
+          npiM30Pct: null,
+        },
+      ],
+    };
+    expect(Object.values(SellerTableSourceStatusEnum)).toEqual(['OK', 'UNAVAILABLE']);
+    expect(response.items[0].npiM30Pct).toBeNull();
+  });
+});

package/bin/retailCommission/dtos/PrivateLatestClosedPayout.d.ts

@@ -0,0 +1,24 @@
+/** Query de `GET /private/retailers/{retailerId}/payouts/latest-closed`. */
+export declare class PrivateLatestClosedPayoutQuery {
+    retailerId: string;
+}
+/** Lo que el corte le paga a un vendedor: liberado más ajustes, en centavos. */
+export interface PrivateClosedPayoutSeller {
+    retailUserId: string;
+    amountCents: number;
+}
+/** El corte semanal; `from` y `to` son días locales `YYYY-MM-DD`, ambos incluidos. */
+export interface PrivateClosedPayoutPeriod {
+    periodId: string;
+    from: string;
+    to: string;
+}
+/**
+ * Respuesta de `GET /private/retailers/{retailerId}/payouts/latest-closed`: el último corte semanal
+ * CERRADO de la cadena. Sin corte cerrado reciente, `period: null` y `sellers: []`.
+ */
+export interface PrivateLatestClosedPayoutResponse {
+    retailerId: string;
+    period: PrivateClosedPayoutPeriod | null;
+    sellers: PrivateClosedPayoutSeller[];
+}

package/bin/retailCommission/dtos/PrivateLatestClosedPayout.js

@@ -0,0 +1,24 @@
+"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.PrivateLatestClosedPayoutQuery = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+/** Query de `GET /private/retailers/{retailerId}/payouts/latest-closed`. */
+class PrivateLatestClosedPayoutQuery {
+}
+exports.PrivateLatestClosedPayoutQuery = PrivateLatestClosedPayoutQuery;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsString)(),
+    (0, class_validator_1.IsNotEmpty)(),
+    __metadata("design:type", String)
+], PrivateLatestClosedPayoutQuery.prototype, "retailerId", void 0);

package/bin/retailCommission/index.d.ts

@@ -27,3 +27,4 @@ export * from './dtos/CommissionCalcTrace';
 export * from './dtos/CommissionAccrual';
 export * from './dtos/CommissionPayout';
 export * from './dtos/CommissionApi';
+export * from './dtos/PrivateLatestClosedPayout';

package/bin/retailCommission/index.js

@@ -46,3 +46,4 @@ __exportStar(require("./dtos/CommissionAccrual"), exports);
 __exportStar(require("./dtos/CommissionPayout"), exports);
 // Contratos HTTP — uno por endpoint
 __exportStar(require("./dtos/CommissionApi"), exports);
+__exportStar(require("./dtos/PrivateLatestClosedPayout"), exports);

package/bin/retailOrg/dtos/requests/PrivateGoalListQuery.d.ts

@@ -0,0 +1,12 @@
+import { GoalTargetTypeEnum } from '../../enums/GoalTargetTypeEnum';
+/**
+ * Query de `GET /private/retailers/{retailerId}/goals` — las metas de un periodo, M2M.
+ * El `retailerId` llega en el path; la seguridad del privado es de red, no de identidad.
+ */
+export declare class PrivateGoalListQuery {
+    retailerId: string;
+    /** Mes calendario `YYYY-MM` (mes 01-12). */
+    periodId: string;
+    /** Si falta, devuelve los dos tipos. */
+    targetType?: GoalTargetTypeEnum;
+}

package/bin/retailOrg/dtos/requests/PrivateGoalListQuery.js

@@ -0,0 +1,40 @@
+"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.PrivateGoalListQuery = void 0;
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const GoalTargetTypeEnum_1 = require("../../enums/GoalTargetTypeEnum");
+/** ULID canónico: 26 chars Crockford base32, primer char 0-7. */
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+/**
+ * Query de `GET /private/retailers/{retailerId}/goals` — las metas de un periodo, M2M.
+ * El `retailerId` llega en el path; la seguridad del privado es de red, no de identidad.
+ */
+class PrivateGoalListQuery {
+}
+exports.PrivateGoalListQuery = PrivateGoalListQuery;
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.Matches)(ULID, { message: 'retailerId debe ser un ULID' }),
+    __metadata("design:type", String)
+], PrivateGoalListQuery.prototype, "retailerId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.Matches)(/^\d{4}-(0[1-9]|1[0-2])$/, { message: 'periodId debe tener formato YYYY-MM (mes 01-12)' }),
+    __metadata("design:type", String)
+], PrivateGoalListQuery.prototype, "periodId", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsEnum)(GoalTargetTypeEnum_1.GoalTargetTypeEnum),
+    __metadata("design:type", String)
+], PrivateGoalListQuery.prototype, "targetType", void 0);

package/bin/retailOrg/dtos/requests/PrivateSellerListQuery.d.ts

@@ -24,4 +24,6 @@ export declare class PrivateSellerListQuery {
      * nunca omite el registro.
      */
     callerService?: string;
+    /** `true` agrega el teléfono de cada vendedor. Por defecto no viaja: es PII. */
+    includePhone?: boolean;
 }

package/bin/retailOrg/dtos/requests/PrivateSellerListQuery.js

@@ -43,3 +43,9 @@ __decorate([
     (0, class_validator_1.Matches)(/^[a-z0-9-]{1,64}$/, { message: 'callerService debe ser el nombre del lambda (kebab-case)' }),
     __metadata("design:type", String)
 ], PrivateSellerListQuery.prototype, "callerService", void 0);
+__decorate([
+    (0, class_transformer_1.Expose)(),
+    (0, class_transformer_1.Transform)(({ value }) => value === true || value === 'true'),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], PrivateSellerListQuery.prototype, "includePhone", void 0);

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

@@ -0,0 +1,8 @@
+import type { GoalListResponse } from './GoalListResponse';
+/**
+ * Respuesta de `GET /private/retailers/{retailerId}/goals`: las metas del periodo con las tres cifras
+ * derivadas. Un periodo sin metas devuelve `goals: []`, no un 404.
+ */
+export interface PrivateGoalListResponse extends GoalListResponse {
+    retailerId: string;
+}

package/bin/retailOrg/dtos/responses/PrivateGoalListResponse.js

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

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

@@ -15,6 +15,8 @@ export interface PrivateSellerDto {
     homeStoreId: string | null;
     commissionTier: string;
     status: RetailUserStatusEnum;
+    /** Teléfono del vendedor. Solo viaja si se pidió `includePhone=true`; `null` si no lo tiene. */
+    phone?: string | null;
 }
 /**
  * Respuesta de `GET /private/sellers?retailerId=…` — el padrón de una cadena, para máquinas.

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

@@ -16,4 +16,6 @@ export interface StoreValidationDto {
     code: string;
     name: string;
     status: StoreStatusEnum;
+    /** Encargado de la tienda (`retailUserId`); `null` si no tiene. Ausente en lambdas viejos. */
+    managerRetailUserId?: string | null;
 }

package/bin/retailOrg/index.d.ts

@@ -37,10 +37,12 @@ export * from './dtos/requests/TransferRetailUserRequest';
 export * from './dtos/requests/GoalListQuery';
 export * from './dtos/requests/GoalUpsertRequest';
 export * from './dtos/requests/GoalPathParams';
+export * from './dtos/requests/PrivateGoalListQuery';
 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/PrivateGoalListResponse';
 export * from './dtos/responses/StoreKpiResponse';
 export * from './dtos/responses/SellerKpiResponse';

package/bin/retailOrg/index.js

@@ -59,11 +59,13 @@ __exportStar(require("./dtos/requests/TransferRetailUserRequest"), exports);
 __exportStar(require("./dtos/requests/GoalListQuery"), exports);
 __exportStar(require("./dtos/requests/GoalUpsertRequest"), exports);
 __exportStar(require("./dtos/requests/GoalPathParams"), exports);
+__exportStar(require("./dtos/requests/PrivateGoalListQuery"), 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/PrivateGoalListResponse"), exports);
 __exportStar(require("./dtos/responses/StoreKpiResponse"), exports);
 __exportStar(require("./dtos/responses/SellerKpiResponse"), exports);

package/bin/retailWizard/dtos/responses/BackofficeSellerTableResponse.d.ts

@@ -0,0 +1,57 @@
+import type { RetailUserStatusEnum } from '../../../retailOrg/enums/RetailUserStatusEnum';
+import type { SellerTableSourceStatusEnum } from '../../enums/SellerTableSourceStatusEnum';
+/** Una fila de la tabla de Vendedores: padrón + ventas de la ventana + meta + comisión. */
+export interface SellerTableRow {
+    retailUserId: string;
+    /** `null` si ni el padrón ni las ventas traen nombre. */
+    name: string | null;
+    /** `null` solo si el vendedor vendió pero ya no está en el padrón. */
+    status: RetailUserStatusEnum | null;
+    phone: string | null;
+    storeId: string | null;
+    storeName: string | null;
+    zoneName: string | null;
+    /** Es el encargado (`managerRetailUserId`) de su tienda. */
+    isStoreAdmin: boolean;
+    /** Sin ventas en la ventana viaja `0`: el barrido es exhaustivo. */
+    salesCount: number;
+    placedCents: number;
+    averageTicketCents: number | null;
+    lastSaleAt: string | null;
+    /** Δ % contra la misma ventana 7 días antes; `null` si la ventana pasa de 7 días o no hubo base. */
+    weekOverWeekChangePct: number | null;
+    /**
+     * Meta mensual (`monthCents` del mes de `to`, hora de CDMX) escalada a los días de la ventana:
+     * `round(monthCents * días / 30)`. `null` sin meta, con metas caídas o con ventana > 90 días.
+     */
+    goalCents: number | null;
+    /** Lo que le pagó el último corte semanal CERRADO (`0` si no le pagó); `null` sin corte o con la fuente caída. */
+    commissionCents: number | null;
+    /** NPI M30: no lo calcula ningún lambda todavía. Siempre `null`. */
+    npiM30Pct: null;
+}
+/** Estado de cada fuente externa. Una fuente `UNAVAILABLE` deja sus campos en `null`, nunca en `0`. */
+export interface SellerTableSources {
+    roster: SellerTableSourceStatusEnum;
+    goals: SellerTableSourceStatusEnum;
+    commission: SellerTableSourceStatusEnum;
+}
+/** Corte semanal del que sale `commissionCents`; días locales `YYYY-MM-DD`, ambos incluidos. */
+export interface SellerTableCommissionPeriod {
+    periodId: string;
+    from: string;
+    to: string;
+}
+/**
+ * `GET /backoffice/sellers/table?from&to&value` — la tabla completa de Vendedores del Portal Admin
+ * VL, sin paginación. Incluye a los vendedores del padrón sin ventas y a los inactivos.
+ */
+export interface BackofficeSellerTableResponse {
+    from: string;
+    to: string | null;
+    /** Las ventas de la ventana pasaron el tope de lectura: los números están recortados. */
+    truncated: boolean;
+    sources: SellerTableSources;
+    commissionPeriod: SellerTableCommissionPeriod | null;
+    items: SellerTableRow[];
+}

package/bin/retailWizard/dtos/responses/BackofficeSellerTableResponse.js

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

package/bin/retailWizard/enums/SellerTableSourceStatusEnum.d.ts

@@ -0,0 +1,5 @@
+/** Si una fuente de la tabla de Vendedores contestó (`OK`) o falló (`UNAVAILABLE`). */
+export declare enum SellerTableSourceStatusEnum {
+    OK = "OK",
+    UNAVAILABLE = "UNAVAILABLE"
+}

package/bin/retailWizard/enums/SellerTableSourceStatusEnum.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SellerTableSourceStatusEnum = void 0;
+/** Si una fuente de la tabla de Vendedores contestó (`OK`) o falló (`UNAVAILABLE`). */
+var SellerTableSourceStatusEnum;
+(function (SellerTableSourceStatusEnum) {
+    SellerTableSourceStatusEnum["OK"] = "OK";
+    SellerTableSourceStatusEnum["UNAVAILABLE"] = "UNAVAILABLE";
+})(SellerTableSourceStatusEnum || (exports.SellerTableSourceStatusEnum = SellerTableSourceStatusEnum = {}));

package/bin/retailWizard/index.d.ts

@@ -135,6 +135,8 @@ export * from './dtos/responses/BackofficeCustomersResponse';
 export * from './dtos/responses/BackofficeCustomerPurchasesResponse';
 export * from './dtos/responses/BackofficeStoreKpisResponse';
 export * from './dtos/responses/BackofficeSellerKpisResponse';
+export * from './enums/SellerTableSourceStatusEnum';
+export * from './dtos/responses/BackofficeSellerTableResponse';
 export * from './events/SaleCompletedV1';
 export * from './events/SaleCancelledV1';
 export * from './events/SaleCompletedV2';

package/bin/retailWizard/index.js

@@ -168,6 +168,8 @@ __exportStar(require("./dtos/responses/BackofficeCustomersResponse"), exports);
 __exportStar(require("./dtos/responses/BackofficeCustomerPurchasesResponse"), exports);
 __exportStar(require("./dtos/responses/BackofficeStoreKpisResponse"), exports);
 __exportStar(require("./dtos/responses/BackofficeSellerKpisResponse"), exports);
+__exportStar(require("./enums/SellerTableSourceStatusEnum"), exports);
+__exportStar(require("./dtos/responses/BackofficeSellerTableResponse"), exports);
 // Contratos de eventos (PascalCase + sufijo V1)
 __exportStar(require("./events/SaleCompletedV1"), exports);
 __exportStar(require("./events/SaleCancelledV1"), exports);

package/package.json

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

package/src/retailCommission/dtos/PrivateLatestClosedPayout.ts

@@ -0,0 +1,33 @@
+import { Expose } from 'class-transformer';
+import { IsNotEmpty, IsString } from 'class-validator';
+
+/** Query de `GET /private/retailers/{retailerId}/payouts/latest-closed`. */
+export class PrivateLatestClosedPayoutQuery {
+    @Expose()
+    @IsString()
+    @IsNotEmpty()
+    retailerId!: string;
+}
+
+/** Lo que el corte le paga a un vendedor: liberado más ajustes, en centavos. */
+export interface PrivateClosedPayoutSeller {
+    retailUserId: string;
+    amountCents: number;
+}
+
+/** El corte semanal; `from` y `to` son días locales `YYYY-MM-DD`, ambos incluidos. */
+export interface PrivateClosedPayoutPeriod {
+    periodId: string;
+    from: string;
+    to: string;
+}
+
+/**
+ * Respuesta de `GET /private/retailers/{retailerId}/payouts/latest-closed`: el último corte semanal
+ * CERRADO de la cadena. Sin corte cerrado reciente, `period: null` y `sellers: []`.
+ */
+export interface PrivateLatestClosedPayoutResponse {
+    retailerId: string;
+    period: PrivateClosedPayoutPeriod | null;
+    sellers: PrivateClosedPayoutSeller[];
+}

package/src/retailCommission/index.ts

@@ -32,3 +32,4 @@ export * from './dtos/CommissionPayout';
 
 // Contratos HTTP — uno por endpoint
 export * from './dtos/CommissionApi';
+export * from './dtos/PrivateLatestClosedPayout';

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

@@ -0,0 +1,27 @@
+import { Expose } from 'class-transformer';
+import { IsEnum, IsOptional, Matches } from 'class-validator';
+import { GoalTargetTypeEnum } from '../../enums/GoalTargetTypeEnum';
+
+/** ULID canónico: 26 chars Crockford base32, primer char 0-7. */
+const ULID = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/;
+
+/**
+ * Query de `GET /private/retailers/{retailerId}/goals` — las metas de un periodo, M2M.
+ * El `retailerId` llega en el path; la seguridad del privado es de red, no de identidad.
+ */
+export class PrivateGoalListQuery {
+    @Expose()
+    @Matches(ULID, { message: 'retailerId debe ser un ULID' })
+    retailerId!: string;
+
+    /** Mes calendario `YYYY-MM` (mes 01-12). */
+    @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. */
+    @Expose()
+    @IsOptional()
+    @IsEnum(GoalTargetTypeEnum)
+    targetType?: GoalTargetTypeEnum;
+}

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

@@ -1,5 +1,5 @@
-import { Expose } from 'class-transformer';
-import { IsEnum, IsOptional, Matches } from 'class-validator';
+import { Expose, Transform } from 'class-transformer';
+import { IsBoolean, 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). */
@@ -40,4 +40,10 @@ export class PrivateSellerListQuery {
     @IsOptional()
     @Matches(/^[a-z0-9-]{1,64}$/, { message: 'callerService debe ser el nombre del lambda (kebab-case)' })
     callerService?: string;
+
+    /** `true` agrega el teléfono de cada vendedor. Por defecto no viaja: es PII. */
+    @Expose()
+    @Transform(({ value }) => value === true || value === 'true')
+    @IsBoolean()
+    includePhone?: boolean;
 }

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

@@ -0,0 +1,9 @@
+import type { GoalListResponse } from './GoalListResponse';
+
+/**
+ * Respuesta de `GET /private/retailers/{retailerId}/goals`: las metas del periodo con las tres cifras
+ * derivadas. Un periodo sin metas devuelve `goals: []`, no un 404.
+ */
+export interface PrivateGoalListResponse extends GoalListResponse {
+    retailerId: string;
+}

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

@@ -16,6 +16,8 @@ export interface PrivateSellerDto {
     homeStoreId: string | null;
     commissionTier: string;
     status: RetailUserStatusEnum;
+    /** Teléfono del vendedor. Solo viaja si se pidió `includePhone=true`; `null` si no lo tiene. */
+    phone?: string | null;
 }
 
 /**

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

@@ -17,4 +17,6 @@ export interface StoreValidationDto {
     code: string;
     name: string;
     status: StoreStatusEnum;
+    /** Encargado de la tienda (`retailUserId`); `null` si no tiene. Ausente en lambdas viejos. */
+    managerRetailUserId?: string | null;
 }

package/src/retailOrg/index.ts

@@ -47,6 +47,7 @@ export * from './dtos/requests/TransferRetailUserRequest';
 export * from './dtos/requests/GoalListQuery';
 export * from './dtos/requests/GoalUpsertRequest';
 export * from './dtos/requests/GoalPathParams';
+export * from './dtos/requests/PrivateGoalListQuery';
 export * from './dtos/requests/KpiQuery';
 export * from './dtos/requests/PrivateSellerListQuery';
 
@@ -54,5 +55,6 @@ export * from './dtos/requests/PrivateSellerListQuery';
 export * from './dtos/responses/RetailerHierarchyResponse';
 export * from './dtos/responses/GoalListResponse';
 export * from './dtos/responses/GoalUpsertResponse';
+export * from './dtos/responses/PrivateGoalListResponse';
 export * from './dtos/responses/StoreKpiResponse';
 export * from './dtos/responses/SellerKpiResponse';

package/src/retailWizard/dtos/responses/BackofficeSellerTableResponse.ts

@@ -0,0 +1,61 @@
+import type { RetailUserStatusEnum } from '../../../retailOrg/enums/RetailUserStatusEnum';
+import type { SellerTableSourceStatusEnum } from '../../enums/SellerTableSourceStatusEnum';
+
+/** Una fila de la tabla de Vendedores: padrón + ventas de la ventana + meta + comisión. */
+export interface SellerTableRow {
+    retailUserId: string;
+    /** `null` si ni el padrón ni las ventas traen nombre. */
+    name: string | null;
+    /** `null` solo si el vendedor vendió pero ya no está en el padrón. */
+    status: RetailUserStatusEnum | null;
+    phone: string | null;
+    storeId: string | null;
+    storeName: string | null;
+    zoneName: string | null;
+    /** Es el encargado (`managerRetailUserId`) de su tienda. */
+    isStoreAdmin: boolean;
+    /** Sin ventas en la ventana viaja `0`: el barrido es exhaustivo. */
+    salesCount: number;
+    placedCents: number;
+    averageTicketCents: number | null;
+    lastSaleAt: string | null;
+    /** Δ % contra la misma ventana 7 días antes; `null` si la ventana pasa de 7 días o no hubo base. */
+    weekOverWeekChangePct: number | null;
+    /**
+     * Meta mensual (`monthCents` del mes de `to`, hora de CDMX) escalada a los días de la ventana:
+     * `round(monthCents * días / 30)`. `null` sin meta, con metas caídas o con ventana > 90 días.
+     */
+    goalCents: number | null;
+    /** Lo que le pagó el último corte semanal CERRADO (`0` si no le pagó); `null` sin corte o con la fuente caída. */
+    commissionCents: number | null;
+    /** NPI M30: no lo calcula ningún lambda todavía. Siempre `null`. */
+    npiM30Pct: null;
+}
+
+/** Estado de cada fuente externa. Una fuente `UNAVAILABLE` deja sus campos en `null`, nunca en `0`. */
+export interface SellerTableSources {
+    roster: SellerTableSourceStatusEnum;
+    goals: SellerTableSourceStatusEnum;
+    commission: SellerTableSourceStatusEnum;
+}
+
+/** Corte semanal del que sale `commissionCents`; días locales `YYYY-MM-DD`, ambos incluidos. */
+export interface SellerTableCommissionPeriod {
+    periodId: string;
+    from: string;
+    to: string;
+}
+
+/**
+ * `GET /backoffice/sellers/table?from&to&value` — la tabla completa de Vendedores del Portal Admin
+ * VL, sin paginación. Incluye a los vendedores del padrón sin ventas y a los inactivos.
+ */
+export interface BackofficeSellerTableResponse {
+    from: string;
+    to: string | null;
+    /** Las ventas de la ventana pasaron el tope de lectura: los números están recortados. */
+    truncated: boolean;
+    sources: SellerTableSources;
+    commissionPeriod: SellerTableCommissionPeriod | null;
+    items: SellerTableRow[];
+}

package/src/retailWizard/enums/SellerTableSourceStatusEnum.ts

@@ -0,0 +1,5 @@
+/** Si una fuente de la tabla de Vendedores contestó (`OK`) o falló (`UNAVAILABLE`). */
+export enum SellerTableSourceStatusEnum {
+    OK = 'OK',
+    UNAVAILABLE = 'UNAVAILABLE',
+}

package/src/retailWizard/index.ts

@@ -160,6 +160,8 @@ export * from './dtos/responses/BackofficeCustomersResponse';
 export * from './dtos/responses/BackofficeCustomerPurchasesResponse';
 export * from './dtos/responses/BackofficeStoreKpisResponse';
 export * from './dtos/responses/BackofficeSellerKpisResponse';
+export * from './enums/SellerTableSourceStatusEnum';
+export * from './dtos/responses/BackofficeSellerTableResponse';
 
 // Contratos de eventos (PascalCase + sufijo V1)
 export * from './events/SaleCompletedV1';