@fiado/api-invoker 5.40.0 → 5.42.0

package/bin/loanCredit/api/LoanCreditBusinessApi.d.ts

@@ -1,6 +1,7 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { ActivationCheckRequest, ActivationCheckResponse, LoanBorrowerResponse, LoanCreditResponse, OriginateLoanCreditRequest, OriginateLoanCreditResponse, QuoteLoanCreditRequest, QuoteLoanCreditResponse, SignLoanCreditRequest, SignLoanCreditResponse, UpsertLoanBorrowerRequest } from "@fiado/type-kit/bin/loanCredit/index.js";
+import { LoanCreditAnalyticsBatchRequest, LoanCreditAnalyticsBatchResponse } from "./dtos/LoanCreditAnalyticsBatch.js";
 import { ILoanCreditBusinessApi } from "./interfaces/ILoanCreditBusinessApi.js";
 /**
  * Publisher HTTP del lambda `loan-credit-business` (componente 09 SureKeep F2 — motor de crédito).
@@ -25,5 +26,6 @@ export default class LoanCreditBusinessApi implements ILoanCreditBusinessApi {
     discard(creditId: string, tenantId: string): Promise<StandardResponse<LoanCreditResponse>>;
     getCredit(creditId: string, tenantId: string): Promise<StandardResponse<LoanCreditResponse>>;
     getBorrowerByRetailCustomer(retailCustomerId: string, tenantId: string): Promise<StandardResponse<LoanBorrowerResponse>>;
+    batchGetCreditAnalytics(input: LoanCreditAnalyticsBatchRequest, tenantId: string): Promise<StandardResponse<LoanCreditAnalyticsBatchResponse>>;
     upsertBorrower(input: UpsertLoanBorrowerRequest, tenantId: string): Promise<StandardResponse<LoanBorrowerResponse>>;
 }

package/bin/loanCredit/api/LoanCreditBusinessApi.js

@@ -58,6 +58,10 @@ let LoanCreditBusinessApi = class LoanCreditBusinessApi {
         const url = `${this.baseUrl}/private/borrowers/by-retail-customer/${encodeURIComponent(retailCustomerId)}?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+    async batchGetCreditAnalytics(input, tenantId) {
+        const url = `${this.baseUrl}/private/credits/analytics?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, input);
+    }
     async upsertBorrower(input, tenantId) {
         const url = `${this.baseUrl}/private/borrowers?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.post(url, input);

package/bin/loanCredit/api/dtos/LoanCreditAnalyticsBatch.d.ts

@@ -0,0 +1,31 @@
+import { LoanCreditStatusEnum } from "@fiado/type-kit/bin/loanCredit/index.js";
+import { ClientLevelEnum } from "@fiado/type-kit/bin/loanScoring/index.js";
+/** Body de `POST /private/credits/analytics`. Hasta 500 ids por request; el caller pagina. */
+export interface LoanCreditAnalyticsBatchRequest {
+    creditIds: string[];
+}
+/**
+ * Lo mínimo de un crédito para contar: eje de riesgo, plan, cifras del enganche, estado y fecha.
+ * CERO PII — ni acreditado, ni nombre, ni teléfono.
+ */
+export interface LoanCreditAnalyticsItem {
+    creditId: string;
+    /** Nivel CONGELADO al originar; ausente en los créditos que se originaron sin SCI. */
+    clientLevelAtOrigination?: ClientLevelEnum;
+    /** Score CONGELADO al originar; ausente en los créditos que se originaron sin SCI. */
+    sciAtOrigination?: number;
+    /** Plan comercial con el que se originó. Es lo que distingue una venta a empleado. */
+    planId: string;
+    equipmentPriceCents: number;
+    downPaymentCents: number;
+    status: LoanCreditStatusEnum;
+    createdAt: string;
+}
+/**
+ * Los ids que no existen simplemente no vuelven; los que DynamoDB no alcanzó a leer salen
+ * NOMBRADOS para que el caller no los cuente como cero.
+ */
+export interface LoanCreditAnalyticsBatchResponse {
+    items: LoanCreditAnalyticsItem[];
+    unresolvedCreditIds: string[];
+}

package/bin/loanCredit/api/dtos/LoanCreditAnalyticsBatch.js

@@ -0,0 +1 @@
+export {};

package/bin/loanCredit/api/interfaces/ILoanCreditBusinessApi.d.ts

@@ -1,5 +1,6 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { ActivationCheckRequest, ActivationCheckResponse, LoanBorrowerResponse, LoanCreditResponse, OriginateLoanCreditRequest, OriginateLoanCreditResponse, QuoteLoanCreditRequest, QuoteLoanCreditResponse, SignLoanCreditRequest, SignLoanCreditResponse, UpsertLoanBorrowerRequest } from "@fiado/type-kit/bin/loanCredit/index.js";
+import { LoanCreditAnalyticsBatchRequest, LoanCreditAnalyticsBatchResponse } from "../dtos/LoanCreditAnalyticsBatch.js";
 /**
  * Contrato del publisher de `loan-credit-business` (componente 09 SureKeep F2 — motor de crédito
  * SOFOM, pista Loan). Endpoints PRIVADOS (VPC) consumidos por `retail-wizard-business` (pasos
@@ -56,6 +57,16 @@ export interface ILoanCreditBusinessApi {
      * `404 BORROWER_NOT_FOUND` si el evento KYC aún no lo hidrató.
      */
     getBorrowerByRetailCustomer(retailCustomerId: string, tenantId: string): Promise<StandardResponse<LoanBorrowerResponse>>;
+    /**
+     * Lee créditos EN LOTE por su id y devuelve solo lo que se cuenta: el eje de riesgo congelado
+     * al originar, el plan, las cifras del enganche, el estado y la fecha. **Cero PII.**
+     *
+     * Se resuelve por BatchGetItem sobre la clave primaria, así que el orden de salida NO es el de
+     * entrada. Un id que no existe no vuelve; uno que DynamoDB no alcanzó a leer vuelve nombrado en
+     * `unresolvedCreditIds` — nunca se confunde «no pude leerlo» con «no existe».
+     * `400 VALIDATION_ERROR` si el lote pasa de 500 ids o trae uno que no es ULID.
+     */
+    batchGetCreditAnalytics(input: LoanCreditAnalyticsBatchRequest, tenantId: string): Promise<StandardResponse<LoanCreditAnalyticsBatchResponse>>;
     /**
      * Upsert idempotente del acreditado por `retailCustomerId` (mismo contrato que el consumidor
      * del evento `CustomerKycVerifiedV1` — fallback operativo mientras la cola no exista).

package/bin/loanCredit/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./api/dtos/LoanCreditAnalyticsBatch.js";
 export * from "./api/interfaces/ILoanCreditBusinessApi.js";
 export { default as LoanCreditBusinessApi } from "./api/LoanCreditBusinessApi.js";
 export * from "./api/interfaces/ILoanCreditDeviceApi.js";

package/bin/loanCredit/index.js

@@ -1,3 +1,4 @@
+export * from "./api/dtos/LoanCreditAnalyticsBatch.js";
 export * from "./api/interfaces/ILoanCreditBusinessApi.js";
 export { default as LoanCreditBusinessApi } from "./api/LoanCreditBusinessApi.js";
 export * from "./api/interfaces/ILoanCreditDeviceApi.js";

package/bin/retailOrg/api/RetailOrgBusinessApi.d.ts

@@ -1,9 +1,9 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
 import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, RetailUserStatusEnum } from "@fiado/type-kit/bin/retailOrg/index.js";
-import { IRetailOrgBusinessApi, StoreRosterStatusFilter } from "./interfaces/IRetailOrgBusinessApi.js";
+import { IRetailOrgBusinessApi, RetailerRosterStatusFilter, StoreRosterStatusFilter } from "./interfaces/IRetailOrgBusinessApi.js";
 /**
- * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 8
+ * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 9
  * endpoints privados de validación. Contrato y semántica completos → `IRetailOrgBusinessApi`.
  *
  * Los paths y el `?tenantId=` fueron verificados contra dev (200 + negativos 400/404) el
@@ -20,6 +20,13 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
     private httpRequest;
     private readonly baseUrl;
     constructor(httpRequest: IHttpRequest);
+    /**
+     * El padrón de retailers del SILO — lo consume la pantalla de analítica del Portal Admin, que
+     * agrega ventas de todo el silo y no de una cadena. Contrato y semántica completos (incluido por
+     * qué `status` SÍ tiene default y por qué acá el estado es el CRUDO, sin cascada del padre)
+     * → `IRetailOrgBusinessApi.listRetailers`.
+     */
+    listRetailers(tenantId: string, status?: RetailerRosterStatusFilter): Promise<StandardResponse<RetailerValidationDto[]>>;
     getRetailer(retailerId: string, tenantId: string): Promise<StandardResponse<RetailerValidationDto>>;
     getRetailerByStore(storeId: string, tenantId: string): Promise<StandardResponse<RetailerValidationDto>>;
     getStore(retailerId: string, storeId: string, tenantId: string): Promise<StandardResponse<StoreValidationDto>>;

package/bin/retailOrg/api/RetailOrgBusinessApi.js

@@ -12,7 +12,7 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from "inversify";
 /**
- * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 8
+ * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 9
  * endpoints privados de validación. Contrato y semántica completos → `IRetailOrgBusinessApi`.
  *
  * Los paths y el `?tenantId=` fueron verificados contra dev (200 + negativos 400/404) el
@@ -31,6 +31,20 @@ let RetailOrgBusinessApi = class RetailOrgBusinessApi {
     constructor(httpRequest) {
         this.httpRequest = httpRequest;
     }
+    /**
+     * El padrón de retailers del SILO — lo consume la pantalla de analítica del Portal Admin, que
+     * agrega ventas de todo el silo y no de una cadena. Contrato y semántica completos (incluido por
+     * qué `status` SÍ tiene default y por qué acá el estado es el CRUDO, sin cascada del padre)
+     * → `IRetailOrgBusinessApi.listRetailers`.
+     */
+    async listRetailers(tenantId, status) {
+        // `URLSearchParams` en vez de concatenar: `status` es opcional y armar el `&status=` a mano
+        // deja un `&status=undefined` en cuanto alguien se distrae.
+        const query = new URLSearchParams({ tenantId });
+        if (status)
+            query.set("status", status);
+        return await this.httpRequest.get(`${this.baseUrl}/private/retailers?${query.toString()}`);
+    }
     async getRetailer(retailerId, tenantId) {
         const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);

package/bin/retailOrg/api/interfaces/IRetailOrgBusinessApi.d.ts

@@ -1,14 +1,16 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, RetailUserStatusEnum, StoreStatusEnum } from "@fiado/type-kit/bin/retailOrg/index.js";
+import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, RetailUserStatusEnum, RetailerStatusEnum, StoreStatusEnum } from "@fiado/type-kit/bin/retailOrg/index.js";
 /**
  * Filtro de `listStoresByRetailer`. `"ALL"` no es un estado de tienda: es la ausencia de filtro, y
  * va en el MISMO parámetro que los estados porque los dos hablan del mismo eje — un segundo flag
  * tipo `includeInactive` admitiría combinaciones sin sentido que alguien tendría que resolver.
  */
 export type StoreRosterStatusFilter = StoreStatusEnum | "ALL";
+/** Filtro de `listRetailers`. Mismo criterio que `StoreRosterStatusFilter`, un nivel más arriba. */
+export type RetailerRosterStatusFilter = RetailerStatusEnum | "ALL";
 /**
  * Contrato del publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1)
- * para sus 8 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
+ * para sus 9 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
  *
  * Consumidores previstos (regla R5 — cruces entre lambdas son SOLO lecturas de validación;
  * ningún lambda escribe en tabla ajena):
@@ -51,6 +53,43 @@ export type StoreRosterStatusFilter = StoreStatusEnum | "ALL";
  * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
  */
 export interface IRetailOrgBusinessApi {
+    /**
+     * `GET /private/retailers` — el **padrón de retailers del SILO**.
+     *
+     * ── 🔴 Por qué este método existe ────────────────────────────────────────────────────────────
+     * Lo consume la pantalla de analítica del Portal Admin, que agrega ventas de TODO el silo y no
+     * de una cadena. Para eso necesita saber **qué retailers existen**, y ningún otro privado lo
+     * dice: `getRetailer` resuelve UNO por id, `getRetailerByStore` el dueño de una tienda, y el
+     * resto baja un nivel. El único que lista cadenas, `publicListRetailers`, va detrás del
+     * `W4Authorizer` (token de usuario, no invocable entre lambdas), pagina, y devuelve el registro
+     * completo con RFC y datos de contacto.
+     *
+     * Es el hermano de `listStoresByRetailer` un nivel más arriba: aquel da las tiendas de UNA
+     * cadena, este da las cadenas. Sin `retailerId` en la firma: el recurso es el silo entero, que
+     * ya lo determina el `tenantId`.
+     *
+     * Devuelve el mismo `RetailerValidationDto` que `getRetailer` — `retailerId`, `name`, `type`,
+     * `status`, `parentId` — **sin ningún campo PII**. Trae el árbol COMPLETO (cadenas raíz +
+     * subdistribuidores + franquicias, a cualquier profundidad): una venta cuelga de una tienda que
+     * pertenece a un retailer de cualquier nivel, así que quedarse en las raíces perdería ventas.
+     *
+     * ⚠️ El `status` es el CRUDO de la fila, NO uno efectivo — a diferencia de `getStore` y
+     * `listStoresByRetailer`, donde sí viene la cascada del padre aplicada. En retail-org un
+     * retailer no hereda el estado de su padre en ninguna lectura: un subdistribuidor `ACTIVE` de
+     * una cadena `SUSPENDED` sale como `ACTIVE`. Si eso importa, cruza el `parentId`.
+     *
+     * ── ⚠️ `status` SÍ tiene default, igual que `listStoresByRetailer` ───────────────────────────
+     * Omitirlo devuelve **solo los `ACTIVE`**. Pasa `"ALL"` para el padrón completo. El default vive
+     * en el lambda, no acá: mandarlo implícito desde el publisher partiría la decisión en dos
+     * lugares que alguien tendría que mantener sincronizados.
+     *
+     * Devuelve `[]` si ningún retailer pasa el filtro. **No hay 404**: el silo siempre existe — lo
+     * garantiza el `tenantId`, que es lo que resolvió el contexto del tenant.
+     *
+     * @throws `400 RETAILER_STATUS_FILTER_INVALID` si `status` no es del catálogo ·
+     *   `400 UNKNOWN_TENANT` sin `tenantId`.
+     */
+    listRetailers(tenantId: string, status?: RetailerRosterStatusFilter): Promise<StandardResponse<RetailerValidationDto[]>>;
     /**
      * GET /private/retailers/{retailerId} — valida que el retailer exista y devuelve su shape mínimo
      * (id, name, type, status, parentId). `status` ya viene con la cascada aplicada (estado efectivo).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.40.0",
+  "version": "5.42.0",
   "description": "Sirve como un puente entre diferentes funciones lambda, facilitando la comunicación entre ellas a través de invocaciones http",
   "type": "module",
   "main": "bin/index.js",

package/src/loanCredit/api/LoanCreditBusinessApi.ts

@@ -14,6 +14,10 @@ import {
     SignLoanCreditResponse,
     UpsertLoanBorrowerRequest,
 } from "@fiado/type-kit/bin/loanCredit/index.js";
+import {
+    LoanCreditAnalyticsBatchRequest,
+    LoanCreditAnalyticsBatchResponse,
+} from "./dtos/LoanCreditAnalyticsBatch.js";
 import { ILoanCreditBusinessApi } from "./interfaces/ILoanCreditBusinessApi.js";
 
 /**
@@ -94,6 +98,14 @@ export default class LoanCreditBusinessApi implements ILoanCreditBusinessApi {
         return await this.httpRequest.get(url);
     }
 
+    async batchGetCreditAnalytics(
+        input: LoanCreditAnalyticsBatchRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<LoanCreditAnalyticsBatchResponse>> {
+        const url = `${this.baseUrl}/private/credits/analytics?tenantId=${encodeURIComponent(tenantId)}`;
+        return await this.httpRequest.post(url, input);
+    }
+
     async upsertBorrower(
         input: UpsertLoanBorrowerRequest,
         tenantId: string,

package/src/loanCredit/api/dtos/LoanCreditAnalyticsBatch.ts

@@ -0,0 +1,34 @@
+import { LoanCreditStatusEnum } from "@fiado/type-kit/bin/loanCredit/index.js";
+import { ClientLevelEnum } from "@fiado/type-kit/bin/loanScoring/index.js";
+
+/** Body de `POST /private/credits/analytics`. Hasta 500 ids por request; el caller pagina. */
+export interface LoanCreditAnalyticsBatchRequest {
+    creditIds: string[];
+}
+
+/**
+ * Lo mínimo de un crédito para contar: eje de riesgo, plan, cifras del enganche, estado y fecha.
+ * CERO PII — ni acreditado, ni nombre, ni teléfono.
+ */
+export interface LoanCreditAnalyticsItem {
+    creditId: string;
+    /** Nivel CONGELADO al originar; ausente en los créditos que se originaron sin SCI. */
+    clientLevelAtOrigination?: ClientLevelEnum;
+    /** Score CONGELADO al originar; ausente en los créditos que se originaron sin SCI. */
+    sciAtOrigination?: number;
+    /** Plan comercial con el que se originó. Es lo que distingue una venta a empleado. */
+    planId: string;
+    equipmentPriceCents: number;
+    downPaymentCents: number;
+    status: LoanCreditStatusEnum;
+    createdAt: string;
+}
+
+/**
+ * Los ids que no existen simplemente no vuelven; los que DynamoDB no alcanzó a leer salen
+ * NOMBRADOS para que el caller no los cuente como cero.
+ */
+export interface LoanCreditAnalyticsBatchResponse {
+    items: LoanCreditAnalyticsItem[];
+    unresolvedCreditIds: string[];
+}

package/src/loanCredit/api/interfaces/ILoanCreditBusinessApi.ts

@@ -12,6 +12,10 @@ import {
     SignLoanCreditResponse,
     UpsertLoanBorrowerRequest,
 } from "@fiado/type-kit/bin/loanCredit/index.js";
+import {
+    LoanCreditAnalyticsBatchRequest,
+    LoanCreditAnalyticsBatchResponse,
+} from "../dtos/LoanCreditAnalyticsBatch.js";
 
 /**
  * Contrato del publisher de `loan-credit-business` (componente 09 SureKeep F2 — motor de crédito
@@ -100,6 +104,20 @@ export interface ILoanCreditBusinessApi {
         tenantId: string,
     ): Promise<StandardResponse<LoanBorrowerResponse>>;
 
+    /**
+     * Lee créditos EN LOTE por su id y devuelve solo lo que se cuenta: el eje de riesgo congelado
+     * al originar, el plan, las cifras del enganche, el estado y la fecha. **Cero PII.**
+     *
+     * Se resuelve por BatchGetItem sobre la clave primaria, así que el orden de salida NO es el de
+     * entrada. Un id que no existe no vuelve; uno que DynamoDB no alcanzó a leer vuelve nombrado en
+     * `unresolvedCreditIds` — nunca se confunde «no pude leerlo» con «no existe».
+     * `400 VALIDATION_ERROR` si el lote pasa de 500 ids o trae uno que no es ULID.
+     */
+    batchGetCreditAnalytics(
+        input: LoanCreditAnalyticsBatchRequest,
+        tenantId: string,
+    ): Promise<StandardResponse<LoanCreditAnalyticsBatchResponse>>;
+
     /**
      * Upsert idempotente del acreditado por `retailCustomerId` (mismo contrato que el consumidor
      * del evento `CustomerKycVerifiedV1` — fallback operativo mientras la cola no exista).

package/src/loanCredit/index.ts

@@ -1,3 +1,4 @@
+export * from "./api/dtos/LoanCreditAnalyticsBatch.js";
 export * from "./api/interfaces/ILoanCreditBusinessApi.js";
 export { default as LoanCreditBusinessApi } from "./api/LoanCreditBusinessApi.js";
 

package/src/retailOrg/api/RetailOrgBusinessApi.ts

@@ -11,11 +11,12 @@ import {
 } from "@fiado/type-kit/bin/retailOrg/index.js";
 import {
     IRetailOrgBusinessApi,
+    RetailerRosterStatusFilter,
     StoreRosterStatusFilter,
 } from "./interfaces/IRetailOrgBusinessApi.js";
 
 /**
- * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 8
+ * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 9
  * endpoints privados de validación. Contrato y semántica completos → `IRetailOrgBusinessApi`.
  *
  * Los paths y el `?tenantId=` fueron verificados contra dev (200 + negativos 400/404) el
@@ -34,6 +35,23 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
 
     constructor(@inject("IHttpRequest") private httpRequest: IHttpRequest) {}
 
+    /**
+     * El padrón de retailers del SILO — lo consume la pantalla de analítica del Portal Admin, que
+     * agrega ventas de todo el silo y no de una cadena. Contrato y semántica completos (incluido por
+     * qué `status` SÍ tiene default y por qué acá el estado es el CRUDO, sin cascada del padre)
+     * → `IRetailOrgBusinessApi.listRetailers`.
+     */
+    async listRetailers(
+        tenantId: string,
+        status?: RetailerRosterStatusFilter,
+    ): Promise<StandardResponse<RetailerValidationDto[]>> {
+        // `URLSearchParams` en vez de concatenar: `status` es opcional y armar el `&status=` a mano
+        // deja un `&status=undefined` en cuanto alguien se distrae.
+        const query = new URLSearchParams({ tenantId });
+        if (status) query.set("status", status);
+        return await this.httpRequest.get(`${this.baseUrl}/private/retailers?${query.toString()}`);
+    }
+
     async getRetailer(
         retailerId: string,
         tenantId: string,

package/src/retailOrg/api/interfaces/IRetailOrgBusinessApi.ts

@@ -6,6 +6,7 @@ import {
     CollectorValidationDto,
     PrivateSellerListResponse,
     RetailUserStatusEnum,
+    RetailerStatusEnum,
     StoreStatusEnum,
 } from "@fiado/type-kit/bin/retailOrg/index.js";
 
@@ -16,9 +17,12 @@ import {
  */
 export type StoreRosterStatusFilter = StoreStatusEnum | "ALL";
 
+/** Filtro de `listRetailers`. Mismo criterio que `StoreRosterStatusFilter`, un nivel más arriba. */
+export type RetailerRosterStatusFilter = RetailerStatusEnum | "ALL";
+
 /**
  * Contrato del publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1)
- * para sus 8 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
+ * para sus 9 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
  *
  * Consumidores previstos (regla R5 — cruces entre lambdas son SOLO lecturas de validación;
  * ningún lambda escribe en tabla ajena):
@@ -61,6 +65,47 @@ export type StoreRosterStatusFilter = StoreStatusEnum | "ALL";
  * Convención CLAUDE.md global: SSM key = nombre del lambda owner de la URL.
  */
 export interface IRetailOrgBusinessApi {
+    /**
+     * `GET /private/retailers` — el **padrón de retailers del SILO**.
+     *
+     * ── 🔴 Por qué este método existe ────────────────────────────────────────────────────────────
+     * Lo consume la pantalla de analítica del Portal Admin, que agrega ventas de TODO el silo y no
+     * de una cadena. Para eso necesita saber **qué retailers existen**, y ningún otro privado lo
+     * dice: `getRetailer` resuelve UNO por id, `getRetailerByStore` el dueño de una tienda, y el
+     * resto baja un nivel. El único que lista cadenas, `publicListRetailers`, va detrás del
+     * `W4Authorizer` (token de usuario, no invocable entre lambdas), pagina, y devuelve el registro
+     * completo con RFC y datos de contacto.
+     *
+     * Es el hermano de `listStoresByRetailer` un nivel más arriba: aquel da las tiendas de UNA
+     * cadena, este da las cadenas. Sin `retailerId` en la firma: el recurso es el silo entero, que
+     * ya lo determina el `tenantId`.
+     *
+     * Devuelve el mismo `RetailerValidationDto` que `getRetailer` — `retailerId`, `name`, `type`,
+     * `status`, `parentId` — **sin ningún campo PII**. Trae el árbol COMPLETO (cadenas raíz +
+     * subdistribuidores + franquicias, a cualquier profundidad): una venta cuelga de una tienda que
+     * pertenece a un retailer de cualquier nivel, así que quedarse en las raíces perdería ventas.
+     *
+     * ⚠️ El `status` es el CRUDO de la fila, NO uno efectivo — a diferencia de `getStore` y
+     * `listStoresByRetailer`, donde sí viene la cascada del padre aplicada. En retail-org un
+     * retailer no hereda el estado de su padre en ninguna lectura: un subdistribuidor `ACTIVE` de
+     * una cadena `SUSPENDED` sale como `ACTIVE`. Si eso importa, cruza el `parentId`.
+     *
+     * ── ⚠️ `status` SÍ tiene default, igual que `listStoresByRetailer` ───────────────────────────
+     * Omitirlo devuelve **solo los `ACTIVE`**. Pasa `"ALL"` para el padrón completo. El default vive
+     * en el lambda, no acá: mandarlo implícito desde el publisher partiría la decisión en dos
+     * lugares que alguien tendría que mantener sincronizados.
+     *
+     * Devuelve `[]` si ningún retailer pasa el filtro. **No hay 404**: el silo siempre existe — lo
+     * garantiza el `tenantId`, que es lo que resolvió el contexto del tenant.
+     *
+     * @throws `400 RETAILER_STATUS_FILTER_INVALID` si `status` no es del catálogo ·
+     *   `400 UNKNOWN_TENANT` sin `tenantId`.
+     */
+    listRetailers(
+        tenantId: string,
+        status?: RetailerRosterStatusFilter,
+    ): Promise<StandardResponse<RetailerValidationDto[]>>;
+
     /**
      * GET /private/retailers/{retailerId} — valida que el retailer exista y devuelve su shape mínimo
      * (id, name, type, status, parentId). `status` ya viene con la cascada aplicada (estado efectivo).