@fiado/api-invoker 5.18.0 → 5.20.0

package/bin/kyc/api/KycVerificationsBusinessApi.d.ts

@@ -2,10 +2,12 @@ import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { IHttpRequest } from "@fiado/http-client";
 import type { KycByDirectoryResponse } from "@fiado/type-kit/bin/kyc/index.js";
 import type { IKycVerificationsBusinessApi } from "./interfaces/IKycVerificationsBusinessApi.js";
+import type { CountryWorkflowResponse } from "./dtos/CountryWorkflowResponse.js";
 /** Contrato y semántica completos → `IKycVerificationsBusinessApi` (`StandardResponse` → leer `result.data`). */
 export declare class KycVerificationsBusinessApi implements IKycVerificationsBusinessApi {
     private httpRequest;
     private readonly baseUrl;
     constructor(httpRequest: IHttpRequest);
     getByDirectory(directoryId: string): Promise<StandardResponse<KycByDirectoryResponse>>;
+    getFlowById(id: string): Promise<StandardResponse<CountryWorkflowResponse>>;
 }

package/bin/kyc/api/KycVerificationsBusinessApi.js

@@ -28,6 +28,12 @@ let KycVerificationsBusinessApi = class KycVerificationsBusinessApi {
         const url = `${this.baseUrl}/verifications/by-directory/${encodeURIComponent(directoryId)}`;
         return await this.httpRequest.get(url);
     }
+    async getFlowById(id) {
+        // SIN prefijo `/private`, por lo mismo que `getByDirectory`: la API que resuelve el SSM es
+        // PRIVADA COMPLETA y sus paths cuelgan de la raíz.
+        const url = `${this.baseUrl}/flows/${encodeURIComponent(id)}`;
+        return await this.httpRequest.get(url);
+    }
 };
 KycVerificationsBusinessApi = __decorate([
     injectable(),

package/bin/kyc/api/dtos/CountryWorkflowResponse.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Una fila del catálogo `CountryWorkflow` de `kyc-verifications-business`: el mapa
+ * `id` → `workflowId` de Metamap.
+ *
+ * ⚠️ El `id` **no siempre es un país**. La tabla arrancó como "flow por país" (`484` = México,
+ * `USA`, `724` = pasaportes de España) pero ya lleva llaves sintéticas para flows que no dependen
+ * del país: `PROOF_OF_ADDRESS` (comprobante de domicilio), `000` (agentes) y `FACEMATCH`. Tratalo
+ * como una llave opaca de catálogo, no como un `CountryId`.
+ *
+ * El backoffice edita estas filas en caliente, así que el valor **puede cambiar sin un deploy**.
+ * Ese es justamente el motivo de leerlo de acá y no de una env var.
+ */
+export interface CountryWorkflowResponse {
+    /** La llave del catálogo: un `CountryId`, o una llave sintética como `FACEMATCH`. */
+    id: string;
+    /** El flow ID de Metamap. Es lo que se manda como `flowId` al widget hospedado. */
+    workflowId: string;
+    /** Texto libre que escribe el backoffice. Puede venir `null`. */
+    description: string | null;
+}

package/bin/kyc/api/dtos/CountryWorkflowResponse.js

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

package/bin/kyc/api/interfaces/IKycVerificationsBusinessApi.d.ts

@@ -1,5 +1,6 @@
 import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { KycByDirectoryResponse } from "@fiado/type-kit/bin/kyc/index.js";
+import type { CountryWorkflowResponse } from "../dtos/CountryWorkflowResponse.js";
 /**
  * Publisher del privado de `kyc-verifications-business`.
  *
@@ -29,4 +30,24 @@ export interface IKycVerificationsBusinessApi {
      * @throws propaga el error del destino; nunca devuelve fallback.
      */
     getByDirectory(directoryId: string): Promise<StandardResponse<KycByDirectoryResponse>>;
+    /**
+     * Una fila del catálogo `CountryWorkflow`: la traducción `id` → `workflowId` de Metamap.
+     *
+     * Es la **fuente canónica** del flow ID. El backoffice edita estas filas en caliente, así que
+     * un consumidor que guarde el flow ID en una env var queda desincronizado en cuanto alguien lo
+     * cambia ahí — sin que nadie se entere hasta que Metamap rechaza la verificación.
+     *
+     * El `id` es una llave opaca de catálogo, NO necesariamente un país: además de los `CountryId`
+     * (`484`, `USA`, `724`) la tabla lleva llaves sintéticas como `PROOF_OF_ADDRESS`, `000` y
+     * `FACEMATCH`.
+     *
+     * ⚠️ Si la llave no existe en el catálogo el destino responde **400**, no 404 — verificado
+     * contra el PR #92 de `kyc-verifications-business`. Es el comportamiento que ya tenía
+     * `CountryWorkflowManager` para el endpoint público y no se cambió para no romperle el
+     * contrato. Un flow que falta es un error de configuración, no un caso vacío: el consumidor
+     * debe fallar ruidoso, nunca degradar a un default.
+     *
+     * @throws propaga el error del destino; nunca devuelve fallback.
+     */
+    getFlowById(id: string): Promise<StandardResponse<CountryWorkflowResponse>>;
 }

package/bin/kyc/index.d.ts

@@ -1,4 +1,5 @@
 export * from './api/interfaces/IKycVerificationsBusinessApi.js';
+export * from './api/dtos/CountryWorkflowResponse.js';
 export * from './api/KycVerificationsBusinessApi.js';
 export * from './queue/interfaces/IRetailKycInboundPublisher.js';
 export * from './queue/RetailKycInboundPublisher.js';

package/bin/kyc/index.js

@@ -1,4 +1,5 @@
 export * from './api/interfaces/IKycVerificationsBusinessApi.js';
+export * from './api/dtos/CountryWorkflowResponse.js';
 export * from './api/KycVerificationsBusinessApi.js';
 export * from './queue/interfaces/IRetailKycInboundPublisher.js';
 export * from './queue/RetailKycInboundPublisher.js';

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

@@ -1,6 +1,6 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto } from "@fiado/type-kit/bin/retailOrg/index.js";
+import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, RetailUserStatusEnum } from "@fiado/type-kit/bin/retailOrg/index.js";
 import { IRetailOrgBusinessApi } from "./interfaces/IRetailOrgBusinessApi.js";
 /**
  * Publisher HTTP del lambda `retail-org-business` (componente 04 SureKeep Fase 1) para sus 6
@@ -26,4 +26,13 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
     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[]>>;
+    /**
+     * SureKeep F3 — el padrón de vendedores que consume el motor de comisiones al cerrar el corte.
+     * Contrato y semántica completos (incluido por qué `status` NO tiene default y por qué
+     * `callerService` es obligatorio) → `IRetailOrgBusinessApi.listSellers`.
+     *
+     * ⚠️ Es el único método de este publisher con el `retailerId` en el QUERY y no anidado en el
+     * path: el caller no está validando un recurso, está pidiendo una colección entera.
+     */
+    listSellers(retailerId: string, tenantId: string, callerService: string, status?: RetailUserStatusEnum): Promise<StandardResponse<PrivateSellerListResponse>>;
 }

package/bin/retailOrg/api/RetailOrgBusinessApi.js

@@ -55,6 +55,22 @@ let RetailOrgBusinessApi = class RetailOrgBusinessApi {
         const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}/collectors?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+    /**
+     * SureKeep F3 — el padrón de vendedores que consume el motor de comisiones al cerrar el corte.
+     * Contrato y semántica completos (incluido por qué `status` NO tiene default y por qué
+     * `callerService` es obligatorio) → `IRetailOrgBusinessApi.listSellers`.
+     *
+     * ⚠️ Es el único método de este publisher con el `retailerId` en el QUERY y no anidado en el
+     * path: el caller no está validando un recurso, está pidiendo una colección entera.
+     */
+    async listSellers(retailerId, tenantId, callerService, 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({ retailerId, tenantId, callerService });
+        if (status)
+            query.set("status", status);
+        return await this.httpRequest.get(`${this.baseUrl}/private/sellers?${query.toString()}`);
+    }
 };
 RetailOrgBusinessApi = __decorate([
     injectable(),

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

@@ -1,5 +1,5 @@
 import { StandardResponse } from "@fiado/gateway-adapter";
-import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto } from "@fiado/type-kit/bin/retailOrg/index.js";
+import { RetailerValidationDto, StoreValidationDto, RetailUserValidationDto, CollectorValidationDto, PrivateSellerListResponse, RetailUserStatusEnum } from "@fiado/type-kit/bin/retailOrg/index.js";
 /**
  * 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).
@@ -102,4 +102,39 @@ export interface IRetailOrgBusinessApi {
      * `result.data`, NO `result.body`). Retorna `[]` (no 404) si el retailer no tiene cobradores activos.
      */
     listActiveCollectorsByRetailer(retailerId: string, tenantId: string): Promise<StandardResponse<CollectorValidationDto[]>>;
+    /**
+     * `GET /private/sellers?retailerId=…` (SureKeep F3) — el **padrón de vendedores** de una cadena.
+     *
+     * ── 🔴 Por qué este método existe ────────────────────────────────────────────────────────────
+     * Lo consume el **motor de comisiones** al cerrar el corte del periodo, para saber a quién hay
+     * que pagarle y abrir una fila de devengo por cada uno. **Sin esta lista el fan-out del cierre
+     * no arranca.** Publicarlo acá es lo que evita que el motor caiga en `DIRECT_HTTP` (antipatrón
+     * duro): entre lambdas de Fiado la comunicación va SIEMPRE por `@fiado/api-invoker`.
+     *
+     * Devuelve el shape mínimo —`sellerId`, `displayName`, `homeStoreId`, `commissionTier`,
+     * `status`— **sin PII de contacto**: nada de teléfono ni `cognitoSub`. `commissionTier` no es
+     * adorno: es lo que el motor usa para resolver CUÁNTO le toca a cada quien según el plan vigente.
+     *
+     * Excluye a los COBRADORES (`commissionTier === 'collector'`), que tienen su propio método
+     * (`listActiveCollectorsByRetailer`) — la cobranza es del otro dominio.
+     *
+     * ── ⚠️ `status` NO tiene default ─────────────────────────────────────────────────────────────
+     * Omitirlo devuelve **TODOS** los estados, no solo los activos. Es deliberado: un vendedor dado
+     * de baja el día 20 **sí tiene comisión** por lo que vendió hasta el 19, y un default `ACTIVE`
+     * lo perdería en silencio sin dejar ninguna forma de pedir el padrón completo. Si el motor
+     * quiere solo activos, que lo diga explícito.
+     *
+     * ── `callerService`: quién exportó la nómina ─────────────────────────────────────────────────
+     * El endpoint es `Feature.ANONIMUS` (sin token de usuario), así que **no hay `actorId`** al que
+     * atribuirle la lectura — y esto exporta la nómina completa de una cadena en una sola llamada.
+     * El lambda destino registra el acceso en `SharedPiiAccessLog_GT` y usa este valor para saber
+     * QUIÉN lo pidió. Si se omite, el registro queda como `m2m:unknown` (con WARN en CloudWatch);
+     * **no lo omitas**: es la única traza que existe de una exportación masiva de datos de empleados.
+     *
+     * @throws `404 RETAILER_NOT_FOUND` si el retailer no existe en ese silo. Un `[]` no distinguiría
+     *   "esta cadena no tiene vendedores" de "preguntaste por una cadena que no existe", y lo segundo
+     *   cerraría el corte sin devengos sin que nadie se entere hasta el día de pago.
+     * @throws `400 VALIDATION_ERROR` si `retailerId` no es un ULID · `400 UNKNOWN_TENANT` sin `tenantId`.
+     */
+    listSellers(retailerId: string, tenantId: string, callerService: string, status?: RetailUserStatusEnum): Promise<StandardResponse<PrivateSellerListResponse>>;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.18.0",
+  "version": "5.20.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",
@@ -34,7 +34,7 @@
     "@fiado/gateway-adapter": "^3.9.0",
     "@fiado/http-client": "^2.0.1",
     "@fiado/logger": "^1.1.3",
-    "@fiado/type-kit": "^3.273.0",
+    "@fiado/type-kit": "^3.276.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/kyc/api/KycVerificationsBusinessApi.ts

@@ -3,6 +3,7 @@ import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { IHttpRequest } from "@fiado/http-client";
 import type { KycByDirectoryResponse } from "@fiado/type-kit/bin/kyc/index.js";
 import type { IKycVerificationsBusinessApi } from "./interfaces/IKycVerificationsBusinessApi.js";
+import type { CountryWorkflowResponse } from "./dtos/CountryWorkflowResponse.js";
 
 /** Contrato y semántica completos → `IKycVerificationsBusinessApi` (`StandardResponse` → leer `result.data`). */
 @injectable()
@@ -22,4 +23,11 @@ export class KycVerificationsBusinessApi implements IKycVerificationsBusinessApi
         const url = `${this.baseUrl}/verifications/by-directory/${encodeURIComponent(directoryId)}`;
         return await this.httpRequest.get<StandardResponse<KycByDirectoryResponse>>(url);
     }
+
+    async getFlowById(id: string): Promise<StandardResponse<CountryWorkflowResponse>> {
+        // SIN prefijo `/private`, por lo mismo que `getByDirectory`: la API que resuelve el SSM es
+        // PRIVADA COMPLETA y sus paths cuelgan de la raíz.
+        const url = `${this.baseUrl}/flows/${encodeURIComponent(id)}`;
+        return await this.httpRequest.get<StandardResponse<CountryWorkflowResponse>>(url);
+    }
 }

package/src/kyc/api/dtos/CountryWorkflowResponse.ts

@@ -0,0 +1,20 @@
+/**
+ * Una fila del catálogo `CountryWorkflow` de `kyc-verifications-business`: el mapa
+ * `id` → `workflowId` de Metamap.
+ *
+ * ⚠️ El `id` **no siempre es un país**. La tabla arrancó como "flow por país" (`484` = México,
+ * `USA`, `724` = pasaportes de España) pero ya lleva llaves sintéticas para flows que no dependen
+ * del país: `PROOF_OF_ADDRESS` (comprobante de domicilio), `000` (agentes) y `FACEMATCH`. Tratalo
+ * como una llave opaca de catálogo, no como un `CountryId`.
+ *
+ * El backoffice edita estas filas en caliente, así que el valor **puede cambiar sin un deploy**.
+ * Ese es justamente el motivo de leerlo de acá y no de una env var.
+ */
+export interface CountryWorkflowResponse {
+    /** La llave del catálogo: un `CountryId`, o una llave sintética como `FACEMATCH`. */
+    id: string;
+    /** El flow ID de Metamap. Es lo que se manda como `flowId` al widget hospedado. */
+    workflowId: string;
+    /** Texto libre que escribe el backoffice. Puede venir `null`. */
+    description: string | null;
+}

package/src/kyc/api/interfaces/IKycVerificationsBusinessApi.ts

@@ -1,5 +1,6 @@
 import type { StandardResponse } from "@fiado/gateway-adapter";
 import type { KycByDirectoryResponse } from "@fiado/type-kit/bin/kyc/index.js";
+import type { CountryWorkflowResponse } from "../dtos/CountryWorkflowResponse.js";
 
 /**
  * Publisher del privado de `kyc-verifications-business`.
@@ -30,4 +31,25 @@ export interface IKycVerificationsBusinessApi {
      * @throws propaga el error del destino; nunca devuelve fallback.
      */
     getByDirectory(directoryId: string): Promise<StandardResponse<KycByDirectoryResponse>>;
+
+    /**
+     * Una fila del catálogo `CountryWorkflow`: la traducción `id` → `workflowId` de Metamap.
+     *
+     * Es la **fuente canónica** del flow ID. El backoffice edita estas filas en caliente, así que
+     * un consumidor que guarde el flow ID en una env var queda desincronizado en cuanto alguien lo
+     * cambia ahí — sin que nadie se entere hasta que Metamap rechaza la verificación.
+     *
+     * El `id` es una llave opaca de catálogo, NO necesariamente un país: además de los `CountryId`
+     * (`484`, `USA`, `724`) la tabla lleva llaves sintéticas como `PROOF_OF_ADDRESS`, `000` y
+     * `FACEMATCH`.
+     *
+     * ⚠️ Si la llave no existe en el catálogo el destino responde **400**, no 404 — verificado
+     * contra el PR #92 de `kyc-verifications-business`. Es el comportamiento que ya tenía
+     * `CountryWorkflowManager` para el endpoint público y no se cambió para no romperle el
+     * contrato. Un flow que falta es un error de configuración, no un caso vacío: el consumidor
+     * debe fallar ruidoso, nunca degradar a un default.
+     *
+     * @throws propaga el error del destino; nunca devuelve fallback.
+     */
+    getFlowById(id: string): Promise<StandardResponse<CountryWorkflowResponse>>;
 }

package/src/kyc/index.ts

@@ -1,4 +1,5 @@
 export * from './api/interfaces/IKycVerificationsBusinessApi.js';
+export * from './api/dtos/CountryWorkflowResponse.js';
 export * from './api/KycVerificationsBusinessApi.js';
 export * from './queue/interfaces/IRetailKycInboundPublisher.js';
 export * from './queue/RetailKycInboundPublisher.js';

package/src/retailOrg/api/RetailOrgBusinessApi.ts

@@ -6,6 +6,8 @@ import {
     StoreValidationDto,
     RetailUserValidationDto,
     CollectorValidationDto,
+    PrivateSellerListResponse,
+    RetailUserStatusEnum,
 } from "@fiado/type-kit/bin/retailOrg/index.js";
 import { IRetailOrgBusinessApi } from "./interfaces/IRetailOrgBusinessApi.js";
 
@@ -78,4 +80,25 @@ export default class RetailOrgBusinessApi implements IRetailOrgBusinessApi {
         const url = `${this.baseUrl}/private/retailers/${encodeURIComponent(retailerId)}/collectors?tenantId=${encodeURIComponent(tenantId)}`;
         return await this.httpRequest.get(url);
     }
+
+    /**
+     * SureKeep F3 — el padrón de vendedores que consume el motor de comisiones al cerrar el corte.
+     * Contrato y semántica completos (incluido por qué `status` NO tiene default y por qué
+     * `callerService` es obligatorio) → `IRetailOrgBusinessApi.listSellers`.
+     *
+     * ⚠️ Es el único método de este publisher con el `retailerId` en el QUERY y no anidado en el
+     * path: el caller no está validando un recurso, está pidiendo una colección entera.
+     */
+    async listSellers(
+        retailerId: string,
+        tenantId: string,
+        callerService: string,
+        status?: RetailUserStatusEnum,
+    ): Promise<StandardResponse<PrivateSellerListResponse>> {
+        // `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({ retailerId, tenantId, callerService });
+        if (status) query.set("status", status);
+        return await this.httpRequest.get(`${this.baseUrl}/private/sellers?${query.toString()}`);
+    }
 }

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

@@ -4,6 +4,8 @@ import {
     StoreValidationDto,
     RetailUserValidationDto,
     CollectorValidationDto,
+    PrivateSellerListResponse,
+    RetailUserStatusEnum,
 } from "@fiado/type-kit/bin/retailOrg/index.js";
 
 /**
@@ -133,4 +135,45 @@ export interface IRetailOrgBusinessApi {
         retailerId: string,
         tenantId: string,
     ): Promise<StandardResponse<CollectorValidationDto[]>>;
+
+    /**
+     * `GET /private/sellers?retailerId=…` (SureKeep F3) — el **padrón de vendedores** de una cadena.
+     *
+     * ── 🔴 Por qué este método existe ────────────────────────────────────────────────────────────
+     * Lo consume el **motor de comisiones** al cerrar el corte del periodo, para saber a quién hay
+     * que pagarle y abrir una fila de devengo por cada uno. **Sin esta lista el fan-out del cierre
+     * no arranca.** Publicarlo acá es lo que evita que el motor caiga en `DIRECT_HTTP` (antipatrón
+     * duro): entre lambdas de Fiado la comunicación va SIEMPRE por `@fiado/api-invoker`.
+     *
+     * Devuelve el shape mínimo —`sellerId`, `displayName`, `homeStoreId`, `commissionTier`,
+     * `status`— **sin PII de contacto**: nada de teléfono ni `cognitoSub`. `commissionTier` no es
+     * adorno: es lo que el motor usa para resolver CUÁNTO le toca a cada quien según el plan vigente.
+     *
+     * Excluye a los COBRADORES (`commissionTier === 'collector'`), que tienen su propio método
+     * (`listActiveCollectorsByRetailer`) — la cobranza es del otro dominio.
+     *
+     * ── ⚠️ `status` NO tiene default ─────────────────────────────────────────────────────────────
+     * Omitirlo devuelve **TODOS** los estados, no solo los activos. Es deliberado: un vendedor dado
+     * de baja el día 20 **sí tiene comisión** por lo que vendió hasta el 19, y un default `ACTIVE`
+     * lo perdería en silencio sin dejar ninguna forma de pedir el padrón completo. Si el motor
+     * quiere solo activos, que lo diga explícito.
+     *
+     * ── `callerService`: quién exportó la nómina ─────────────────────────────────────────────────
+     * El endpoint es `Feature.ANONIMUS` (sin token de usuario), así que **no hay `actorId`** al que
+     * atribuirle la lectura — y esto exporta la nómina completa de una cadena en una sola llamada.
+     * El lambda destino registra el acceso en `SharedPiiAccessLog_GT` y usa este valor para saber
+     * QUIÉN lo pidió. Si se omite, el registro queda como `m2m:unknown` (con WARN en CloudWatch);
+     * **no lo omitas**: es la única traza que existe de una exportación masiva de datos de empleados.
+     *
+     * @throws `404 RETAILER_NOT_FOUND` si el retailer no existe en ese silo. Un `[]` no distinguiría
+     *   "esta cadena no tiene vendedores" de "preguntaste por una cadena que no existe", y lo segundo
+     *   cerraría el corte sin devengos sin que nadie se entere hasta el día de pago.
+     * @throws `400 VALIDATION_ERROR` si `retailerId` no es un ULID · `400 UNKNOWN_TENANT` sin `tenantId`.
+     */
+    listSellers(
+        retailerId: string,
+        tenantId: string,
+        callerService: string,
+        status?: RetailUserStatusEnum,
+    ): Promise<StandardResponse<PrivateSellerListResponse>>;
 }