@fiado/api-invoker 5.40.0 → 5.41.0

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.41.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/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).