@fiado/api-invoker 5.22.0 → 5.24.0

package/bin/card/CardApi.d.ts

@@ -1,6 +1,6 @@
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
-import { IHttpRequest } from "@fiado/http-client";
-import { CardIssuanceObservationUpdateRequest, CardResponse, CardUpdateIssuanceRequest, Status, UpdateBankAccountCardRequest } from "@fiado/type-kit/bin/card/index.js";
+import type { IHttpRequest } from "@fiado/http-client";
+import { CardApplicationRequest, CardIssuanceObservationUpdateRequest, CardResponse, CardUpdateIssuanceRequest, Status, UpdateBankAccountCardRequest } from "@fiado/type-kit/bin/card/index.js";
 import { CardsByStatusResponse, ICardApi } from "./interfaces/ICardApi.js";
 import { Provider } from "@fiado/type-kit/bin/provider/index.js";
 import { InfoSelfVerifiedStatus } from "@fiado/type-kit/bin/identity/index.js";
@@ -19,4 +19,5 @@ export declare class CardApi implements ICardApi {
     updateIssuanceObservation(directoryId: string, input: CardIssuanceObservationUpdateRequest): Promise<ApiGatewayResponse<void>>;
     issuance(directoryId: string, USA_InfoSelfVerified: InfoSelfVerifiedStatus): Promise<void>;
     updateShipping(provider: Provider, shippingId: string, input: UpdateBankAccountCardRequest): Promise<ApiGatewayResponse<void>>;
+    cardApplication(directoryId: string, provider: Provider, input: CardApplicationRequest): Promise<void>;
 }

package/bin/card/CardApi.js

@@ -70,6 +70,13 @@ let CardApi = class CardApi {
         const url = `${this.baseUrl}${provider}/shipping/${shippingId}`;
         return await this.httpRequest.put(url, input);
     }
+    async cardApplication(directoryId, provider, input) {
+        const url = `${this.baseUrl}cards/virtual`;
+        // `directoryId` y `provider` van DESPUES del spread a proposito: son los
+        // dos campos que el endpoint exige, y un `input` que los trajera con
+        // otro valor no debe poder pisarlos.
+        await this.httpRequest.post(url, { ...input, directoryId, provider });
+    }
 };
 CardApi = __decorate([
     injectable(),

package/bin/card/interfaces/ICardApi.d.ts

@@ -1,5 +1,5 @@
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
-import { CardIssuanceObservationUpdateRequest, CardResponse, CardUpdateIssuanceRequest, Status, UpdateBankAccountCardRequest } from "@fiado/type-kit/bin/card/index.js";
+import { CardApplicationRequest, CardIssuanceObservationUpdateRequest, CardResponse, CardUpdateIssuanceRequest, Status, UpdateBankAccountCardRequest } from "@fiado/type-kit/bin/card/index.js";
 import { InfoSelfVerifiedStatus } from "@fiado/type-kit/bin/identity/index.js";
 import { Provider } from "@fiado/type-kit/bin/provider/index.js";
 export interface CardsByStatusResponse {
@@ -17,4 +17,27 @@ export interface ICardApi {
     updateIssuanceObservation(directoryId: string, input: CardIssuanceObservationUpdateRequest): Promise<ApiGatewayResponse<void>>;
     issuance(directoryId: string, USA_InfoSelfVerified: InfoSelfVerifiedStatus): Promise<void>;
     updateShipping(provider: Provider, shippingId: string, input: UpdateBankAccountCardRequest): Promise<ApiGatewayResponse<void>>;
+    /**
+     * Emite la tarjeta virtual de un directorio y la registra en
+     * `fiado-card-business`, invocable SERVICIO-A-SERVICIO.
+     *
+     * Hasta esta version esta interfaz declaraba diez metodos y **ninguno
+     * creaba tarjetas**: la creacion existia solo en tres rutas humanas
+     * (`publicCardApplication`, `agentsCardApplication`,
+     * `backofficeCardApplication`), detras de autorizacion de usuario o de
+     * agente. Eso dejaba a `account-issuance-business` —que crea la cuenta de
+     * Pomelo— sin forma de completarla con su tarjeta.
+     *
+     * `directoryId` y `provider` viajan en el BODY, no en la ruta: el endpoint
+     * es de servicio y no hay token del que sacar el directorio, a diferencia
+     * de `publicCardApplication`.
+     *
+     * **Es idempotente del lado del servidor**: si el directorio ya tiene una
+     * tarjeta virtual no cancelada para ese proveedor, no se llama al proveedor
+     * y responde 200 igual. El llamador puede reintentar sin duplicar.
+     *
+     * Devuelve `void`: la ruta no responde la tarjeta creada, asi que el exito
+     * es "no lanzo". Un fallo llega como error HTTP.
+     */
+    cardApplication(directoryId: string, provider: Provider, input: CardApplicationRequest): Promise<void>;
 }

package/bin/platformRbac/resolver/ApiInvokerPermissionResolver.js

@@ -38,7 +38,18 @@ let ApiInvokerPermissionResolver = class ApiInvokerPermissionResolver {
     }
     async resolve(input) {
         const cacheable = input.roleAssignmentsFromToken === undefined;
-        const key = `${input.issuer ?? ""}#${input.cognitoSub}`;
+        // DEC-RBAC-124: el tipo de principal entra en la cache key. NO es defensa contra colisión
+        // —los subs de integración llevan prefijo `INT#` y no chocan con un UUID de Cognito— sino
+        // para que el canal quede explícito y un cambio futuro de formato no cause aliasing
+        // silencioso entre un usuario y una integración.
+        //
+        // Se lee con cast en vez de tiparlo desde `ResolveInput` A PROPÓSITO: `principalType` recién
+        // existe en `@fiado/gateway-adapter` 4.x, y esta lib la consume toda la flota. Atarla al
+        // prerelease obligaría a todos a subir de major. Así compila igual contra 3.x y 4.x, y el
+        // reenvío al endpoint privado funciona en runtime porque `resolvePermissions(input)` manda
+        // el objeto entero sin filtrar campos.
+        const principalType = input.principalType ?? "USER";
+        const key = `${principalType}#${input.issuer ?? ""}#${input.cognitoSub}`;
         if (cacheable) {
             const hit = this._cache.get(key);
             if (hit)

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 } from "./interfaces/IRetailOrgBusinessApi.js";
+import { IRetailOrgBusinessApi, StoreRosterStatusFilter } from "./interfaces/IRetailOrgBusinessApi.js";
 /**
- * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 6
+ * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 8
  * 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
@@ -23,6 +23,13 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
     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>>;
+    /**
+     * SureKeep F3 — el padrón de tiendas que le faltaba al tablero de cohorte de «Análisis de
+     * ventas»: sin él, la tienda que lleva 60 días sin vender no existe para el tablero. Contrato y
+     * semántica completos (incluido por qué acá `status` SÍ tiene default y en `listSellers` no)
+     * → `IRetailOrgBusinessApi.listStoresByRetailer`.
+     */
+    listStoresByRetailer(retailerId: string, tenantId: string, status?: StoreRosterStatusFilter): Promise<StandardResponse<StoreValidationDto[]>>;
     getStoreUsers(retailerId: string, storeId: string, tenantId: string): Promise<StandardResponse<RetailUserValidationDto[]>>;
     getUserByCognitoSub(cognitoSub: string, tenantId: string): Promise<StandardResponse<RetailUserValidationDto>>;
     listActiveCollectorsByRetailer(retailerId: string, tenantId: string): Promise<StandardResponse<CollectorValidationDto[]>>;

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 6
+ * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 8
  * 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
@@ -43,6 +43,21 @@ let RetailOrgBusinessApi = class RetailOrgBusinessApi {
         const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}/stores/${encodeURIComponent(storeId)}?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+    /**
+     * SureKeep F3 — el padrón de tiendas que le faltaba al tablero de cohorte de «Análisis de
+     * ventas»: sin él, la tienda que lleva 60 días sin vender no existe para el tablero. Contrato y
+     * semántica completos (incluido por qué acá `status` SÍ tiene default y en `listSellers` no)
+     * → `IRetailOrgBusinessApi.listStoresByRetailer`.
+     */
+    async listStoresByRetailer(retailerId, 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);
+        const path = `/private/retailers/${encodeURIComponent(retailerId)}/stores`;
+        return await this.httpRequest.get(`${this.baseUrl}${path}?${query.toString()}`);
+    }
     async getStoreUsers(retailerId, storeId, tenantId) {
         const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}/users/by-store/${encodeURIComponent(storeId)}?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);

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

@@ -1,8 +1,14 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, RetailUserStatusEnum } from "@fiado/type-kit/bin/retailOrg/index.js";
+import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, RetailUserStatusEnum, 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";
 /**
  * Contrato del publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1)
- * para sus 6 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
+ * para sus 8 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):
@@ -12,7 +18,7 @@ import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, Col
  *   - `loan-collector-assignment-business` → lista cobradores ACTIVE del retailer para asignar cartera
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * `tenantId` es OBLIGATORIO en los 4 métodos — no es un detalle de firma.
+ * `tenantId` es OBLIGATORIO en TODOS los métodos — no es un detalle de firma.
  * ─────────────────────────────────────────────────────────────────────────────
  * Los privados NO llevan token de usuario (`Feature.ANONIMUS`; la protección es la red VPC),
  * así que el lambda destino no tiene `AuthContext.issuer` y NO puede inferir el silo. El caller
@@ -75,6 +81,42 @@ export interface IRetailOrgBusinessApi {
      * @throws si la tienda no existe o es de OTRO retailer (`404 STORE_NOT_FOUND` — verificado en dev).
      */
     getStore(retailerId: string, storeId: string, tenantId: string): Promise<StandardResponse<StoreValidationDto>>;
+    /**
+     * `GET /private/retailers/{retailerId}/stores` (SureKeep F3) — el **padrón de tiendas** de una
+     * cadena.
+     *
+     * ── 🔴 Por qué este método existe ────────────────────────────────────────────────────────────
+     * Lo consume el tablero de cohorte de «Análisis de ventas» (`retail-wizard-business`), que arma
+     * la lista de tiendas a partir de las VENTAS que leyó. Con eso, **la tienda que lleva 60 días sin
+     * vender no existe para el tablero** — y es exactamente la que hay que mirar. Este es el único
+     * endpoint que sirve el padrón completo: `getStore` resuelve UNA tienda y `publicListStores` va
+     * detrás del `W4Authorizer` (token de usuario, no invocable entre lambdas).
+     *
+     * NO se deriva de `listSellers`: ese endpoint escribe en `SharedPiiAccessLog_GT` y esa bitácora
+     * es la única traza de una exportación masiva de datos de empleados. Pedirle ids de tienda la
+     * llenaría de filas con una intención falsa.
+     *
+     * Devuelve el mismo `StoreValidationDto` que `getStore` — `storeId`, `retailerId`, `zoneId`,
+     * `zoneName`, `code`, `name`, `status` — con el `status` EFECTIVO (cascada del retailer padre ya
+     * aplicada). El `zoneName` sale de la tabla de zonas del propio retail-org: el consumidor no
+     * puede resolver un `zoneId` de otro dominio, y hoy lo saca de un snapshot congelado en la venta,
+     * así que una tienda re-zonificada muestra la zona vieja.
+     *
+     * ── ⚠️ `status` SÍ tiene default, al revés que `listSellers` ─────────────────────────────────
+     * Omitirlo devuelve **solo las `ACTIVE`**. La asimetría es deliberada: allá un vendedor dado de
+     * baja el día 20 sí tiene comisión por lo que vendió hasta el 19, así que filtrar lo perdería.
+     * Acá el consumidor cruza este padrón con ventas que YA leyó, o sea que la tienda cerrada que
+     * vendió dentro de la ventana entra igual por el lado de las ventas — filtrar no puede perder
+     * una tienda que vendió, solo evita agregar un cero permanente a un tablero cuyo trabajo es que
+     * las filas en cero llamen la atención. Pasa `"ALL"` para el padrón completo.
+     *
+     * @throws `404 RETAILER_NOT_FOUND` si el retailer no existe en ese silo. Un `[]` no distinguiría
+     *   "esta cadena no tiene tiendas" de "preguntaste por una cadena que no existe", y lo segundo
+     *   dejaría el tablero mudo sin que nadie sospeche del request.
+     * @throws `400 STORE_STATUS_FILTER_INVALID` si `status` no es del catálogo · `400 UNKNOWN_TENANT`
+     *   sin `tenantId`.
+     */
+    listStoresByRetailer(retailerId: string, tenantId: string, status?: StoreRosterStatusFilter): Promise<StandardResponse<StoreValidationDto[]>>;
     /**
      * GET /private/retailers/{retailerId}/users/by-store/{storeId} — usuarios retail cuya tienda base
      * (`homeStoreId`) es esa. Devuelve `[]` (no 404) si la tienda no tiene usuarios asignados.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.22.0",
+  "version": "5.24.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/card/CardApi.ts

@@ -1,6 +1,11 @@
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
-import { IHttpRequest } from "@fiado/http-client";
-import { CardIssuanceObservationUpdateRequest, CardResponse, CardUpdateIssuanceRequest, Status, UpdateBankAccountCardRequest } from "@fiado/type-kit/bin/card/index.js";
+// `import type`: `IHttpRequest` es una interfaz, y el import de VALOR rompe
+// bajo ESM en jest ("does not provide an export named 'IHttpRequest'"), que es
+// lo que impedia testear esta clase. Mismo estilo que los demas Api del repo
+// que si tienen suite (p. ej. `RetailCardsBusinessApi`). No cambia el runtime:
+// tsc borra las dos formas por igual.
+import type { IHttpRequest } from "@fiado/http-client";
+import { CardApplicationRequest, CardIssuanceObservationUpdateRequest, CardResponse, CardUpdateIssuanceRequest, Status, UpdateBankAccountCardRequest } from "@fiado/type-kit/bin/card/index.js";
 import { inject, injectable } from "inversify";
 import { CardsByStatusResponse, ICardApi } from "./interfaces/ICardApi.js";
 import { Provider } from "@fiado/type-kit/bin/provider/index.js";
@@ -96,6 +101,15 @@ export class CardApi implements ICardApi {
         return await this.httpRequest.put(url, input);
     }
 
+    async cardApplication(directoryId: string, provider: Provider, input: CardApplicationRequest): Promise<void> {
+
+        const url = `${this.baseUrl}cards/virtual`;
+        // `directoryId` y `provider` van DESPUES del spread a proposito: son los
+        // dos campos que el endpoint exige, y un `input` que los trajera con
+        // otro valor no debe poder pisarlos.
+        await this.httpRequest.post(url, { ...input, directoryId, provider });
+    }
+
 }
 
 

package/src/card/interfaces/ICardApi.ts

@@ -1,5 +1,5 @@
 import { ApiGatewayResponse } from "@fiado/gateway-adapter";
-import { CardIssuanceObservationUpdateRequest, CardResponse, CardUpdateIssuanceRequest, Status, UpdateBankAccountCardRequest } from "@fiado/type-kit/bin/card/index.js";
+import { CardApplicationRequest, CardIssuanceObservationUpdateRequest, CardResponse, CardUpdateIssuanceRequest, Status, UpdateBankAccountCardRequest } from "@fiado/type-kit/bin/card/index.js";
 import { InfoSelfVerifiedStatus } from "@fiado/type-kit/bin/identity/index.js";
 import { Provider } from "@fiado/type-kit/bin/provider/index.js";
 
@@ -30,4 +30,28 @@ export interface ICardApi {
 
     updateShipping(provider: Provider, shippingId: string, input: UpdateBankAccountCardRequest): Promise<ApiGatewayResponse<void>>;
 
+    /**
+     * Emite la tarjeta virtual de un directorio y la registra en
+     * `fiado-card-business`, invocable SERVICIO-A-SERVICIO.
+     *
+     * Hasta esta version esta interfaz declaraba diez metodos y **ninguno
+     * creaba tarjetas**: la creacion existia solo en tres rutas humanas
+     * (`publicCardApplication`, `agentsCardApplication`,
+     * `backofficeCardApplication`), detras de autorizacion de usuario o de
+     * agente. Eso dejaba a `account-issuance-business` —que crea la cuenta de
+     * Pomelo— sin forma de completarla con su tarjeta.
+     *
+     * `directoryId` y `provider` viajan en el BODY, no en la ruta: el endpoint
+     * es de servicio y no hay token del que sacar el directorio, a diferencia
+     * de `publicCardApplication`.
+     *
+     * **Es idempotente del lado del servidor**: si el directorio ya tiene una
+     * tarjeta virtual no cancelada para ese proveedor, no se llama al proveedor
+     * y responde 200 igual. El llamador puede reintentar sin duplicar.
+     *
+     * Devuelve `void`: la ruta no responde la tarjeta creada, asi que el exito
+     * es "no lanzo". Un fallo llega como error HTTP.
+     */
+    cardApplication(directoryId: string, provider: Provider, input: CardApplicationRequest): Promise<void>;
+
 }

package/src/platformRbac/resolver/ApiInvokerPermissionResolver.ts

@@ -31,7 +31,18 @@ export class ApiInvokerPermissionResolver {
     }
     async resolve(input: ResolveInput): Promise<ResolvedPermissions> {
         const cacheable = input.roleAssignmentsFromToken === undefined;
-        const key = `${input.issuer ?? ""}#${input.cognitoSub}`;
+        // DEC-RBAC-124: el tipo de principal entra en la cache key. NO es defensa contra colisión
+        // —los subs de integración llevan prefijo `INT#` y no chocan con un UUID de Cognito— sino
+        // para que el canal quede explícito y un cambio futuro de formato no cause aliasing
+        // silencioso entre un usuario y una integración.
+        //
+        // Se lee con cast en vez de tiparlo desde `ResolveInput` A PROPÓSITO: `principalType` recién
+        // existe en `@fiado/gateway-adapter` 4.x, y esta lib la consume toda la flota. Atarla al
+        // prerelease obligaría a todos a subir de major. Así compila igual contra 3.x y 4.x, y el
+        // reenvío al endpoint privado funciona en runtime porque `resolvePermissions(input)` manda
+        // el objeto entero sin filtrar campos.
+        const principalType = (input as { principalType?: string }).principalType ?? "USER";
+        const key = `${principalType}#${input.issuer ?? ""}#${input.cognitoSub}`;
         if (cacheable) {
             const hit = this._cache.get(key);
             if (hit) return hit;

package/src/retailOrg/api/RetailOrgBusinessApi.ts

@@ -9,10 +9,13 @@ import {
     PrivateSellerListResponse,
     RetailUserStatusEnum,
 } from "@fiado/type-kit/bin/retailOrg/index.js";
-import { IRetailOrgBusinessApi } from "./interfaces/IRetailOrgBusinessApi.js";
+import {
+    IRetailOrgBusinessApi,
+    StoreRosterStatusFilter,
+} from "./interfaces/IRetailOrgBusinessApi.js";
 
 /**
- * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 6
+ * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 8
  * 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
@@ -56,6 +59,25 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
         return await this.httpRequest.get(url);
     }
 
+    /**
+     * SureKeep F3 — el padrón de tiendas que le faltaba al tablero de cohorte de «Análisis de
+     * ventas»: sin él, la tienda que lleva 60 días sin vender no existe para el tablero. Contrato y
+     * semántica completos (incluido por qué acá `status` SÍ tiene default y en `listSellers` no)
+     * → `IRetailOrgBusinessApi.listStoresByRetailer`.
+     */
+    async listStoresByRetailer(
+        retailerId: string,
+        tenantId: string,
+        status?: StoreRosterStatusFilter,
+    ): Promise<StandardResponse<StoreValidationDto[]>> {
+        // `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);
+        const path = `/private/retailers/${encodeURIComponent(retailerId)}/stores`;
+        return await this.httpRequest.get(`${this.baseUrl}${path}?${query.toString()}`);
+    }
+
     async getStoreUsers(
         retailerId: string,
         storeId: string,

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

@@ -6,11 +6,19 @@ import {
     CollectorValidationDto,
     PrivateSellerListResponse,
     RetailUserStatusEnum,
+    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";
+
 /**
  * Contrato del publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1)
- * para sus 6 endpoints privados de VALIDACIÓN (service-to-service, VPC-only).
+ * para sus 8 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):
@@ -20,7 +28,7 @@ import {
  *   - `loan-collector-assignment-business` → lista cobradores ACTIVE del retailer para asignar cartera
  *
  * ─────────────────────────────────────────────────────────────────────────────
- * `tenantId` es OBLIGATORIO en los 4 métodos — no es un detalle de firma.
+ * `tenantId` es OBLIGATORIO en TODOS los métodos — no es un detalle de firma.
  * ─────────────────────────────────────────────────────────────────────────────
  * Los privados NO llevan token de usuario (`Feature.ANONIMUS`; la protección es la red VPC),
  * así que el lambda destino no tiene `AuthContext.issuer` y NO puede inferir el silo. El caller
@@ -96,6 +104,47 @@ export interface IRetailOrgBusinessApi {
         tenantId: string,
     ): Promise<StandardResponse<StoreValidationDto>>;
 
+    /**
+     * `GET /private/retailers/{retailerId}/stores` (SureKeep F3) — el **padrón de tiendas** de una
+     * cadena.
+     *
+     * ── 🔴 Por qué este método existe ────────────────────────────────────────────────────────────
+     * Lo consume el tablero de cohorte de «Análisis de ventas» (`retail-wizard-business`), que arma
+     * la lista de tiendas a partir de las VENTAS que leyó. Con eso, **la tienda que lleva 60 días sin
+     * vender no existe para el tablero** — y es exactamente la que hay que mirar. Este es el único
+     * endpoint que sirve el padrón completo: `getStore` resuelve UNA tienda y `publicListStores` va
+     * detrás del `W4Authorizer` (token de usuario, no invocable entre lambdas).
+     *
+     * NO se deriva de `listSellers`: ese endpoint escribe en `SharedPiiAccessLog_GT` y esa bitácora
+     * es la única traza de una exportación masiva de datos de empleados. Pedirle ids de tienda la
+     * llenaría de filas con una intención falsa.
+     *
+     * Devuelve el mismo `StoreValidationDto` que `getStore` — `storeId`, `retailerId`, `zoneId`,
+     * `zoneName`, `code`, `name`, `status` — con el `status` EFECTIVO (cascada del retailer padre ya
+     * aplicada). El `zoneName` sale de la tabla de zonas del propio retail-org: el consumidor no
+     * puede resolver un `zoneId` de otro dominio, y hoy lo saca de un snapshot congelado en la venta,
+     * así que una tienda re-zonificada muestra la zona vieja.
+     *
+     * ── ⚠️ `status` SÍ tiene default, al revés que `listSellers` ─────────────────────────────────
+     * Omitirlo devuelve **solo las `ACTIVE`**. La asimetría es deliberada: allá un vendedor dado de
+     * baja el día 20 sí tiene comisión por lo que vendió hasta el 19, así que filtrar lo perdería.
+     * Acá el consumidor cruza este padrón con ventas que YA leyó, o sea que la tienda cerrada que
+     * vendió dentro de la ventana entra igual por el lado de las ventas — filtrar no puede perder
+     * una tienda que vendió, solo evita agregar un cero permanente a un tablero cuyo trabajo es que
+     * las filas en cero llamen la atención. Pasa `"ALL"` para el padrón completo.
+     *
+     * @throws `404 RETAILER_NOT_FOUND` si el retailer no existe en ese silo. Un `[]` no distinguiría
+     *   "esta cadena no tiene tiendas" de "preguntaste por una cadena que no existe", y lo segundo
+     *   dejaría el tablero mudo sin que nadie sospeche del request.
+     * @throws `400 STORE_STATUS_FILTER_INVALID` si `status` no es del catálogo · `400 UNKNOWN_TENANT`
+     *   sin `tenantId`.
+     */
+    listStoresByRetailer(
+        retailerId: string,
+        tenantId: string,
+        status?: StoreRosterStatusFilter,
+    ): Promise<StandardResponse<StoreValidationDto[]>>;
+
     /**
      * GET /private/retailers/{retailerId}/users/by-store/{storeId} — usuarios retail cuya tienda base
      * (`homeStoreId`) es esa. Devuelve `[]` (no 404) si la tienda no tiene usuarios asignados.