@fiado/api-invoker 5.94.0 → 5.96.0

package/bin/directories/DirectoriesApi.d.ts

@@ -1,6 +1,7 @@
-import { IHttpRequest } from "@fiado/http-client";
+import type { IHttpRequest } from "@fiado/http-client";
 import { IDirectoriesApi } from "./interfaces/IDirectoriesApi.js";
 import { DirectoryBackofficeResponse, DirectoryBackofficeCreateRequest, DirectoryBackofficeUpdateRequest, TypeOfDirectoryId } from '@fiado/type-kit/bin/directory/index.js';
+import type { DirectoryAgentsBySponsorResponse } from '@fiado/type-kit/bin/directory/index.js';
 type FiadoApiResponse<T> = import('@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js').default<T>;
 export declare class DirectoriesApi implements IDirectoriesApi {
     private httpRequest;
@@ -24,5 +25,6 @@ export declare class DirectoriesApi implements IDirectoriesApi {
     updateBackofficeDirectory(directoryId: string, params: DirectoryBackofficeUpdateRequest & {
         typeOfDirectoryId?: TypeOfDirectoryId;
     }): Promise<FiadoApiResponse<DirectoryBackofficeResponse>>;
+    getAgentDirectoriesBySponsorDirectoryIds(sponsorDirectoryIds: string[]): Promise<DirectoryAgentsBySponsorResponse>;
 }
 export {};

package/bin/directories/DirectoriesApi.js

@@ -12,6 +12,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import dotenv from 'dotenv';
 import { inject, injectable } from "inversify";
+import { DIRECTORY_AGENTS_BY_SPONSOR_MAX_BATCH } from '@fiado/type-kit/bin/directory/index.js';
+import { joinUrl } from "../utils/joinUrl.js";
+import { postIdsInBatches } from "../utils/postIdsInBatches.js";
 dotenv.config();
 let DirectoriesApi = class DirectoriesApi {
     httpRequest;
@@ -60,6 +63,10 @@ let DirectoriesApi = class DirectoriesApi {
         const url = `${this.baseUrl}directories/backoffice/${directoryId}`;
         return await this.httpRequest.put(url, params);
     }
+    async getAgentDirectoriesBySponsorDirectoryIds(sponsorDirectoryIds) {
+        const url = joinUrl(this.baseUrl, "directories/search/by-sponsor-directory-ids");
+        return await postIdsInBatches(this.httpRequest, url, "sponsorDirectoryIds", sponsorDirectoryIds, DIRECTORY_AGENTS_BY_SPONSOR_MAX_BATCH);
+    }
 };
 DirectoriesApi = __decorate([
     injectable(),

package/bin/directories/interfaces/IDirectoriesApi.d.ts

@@ -1,5 +1,6 @@
 type FiadoApiResponse<T> = import('@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js').default<T>;
 import { DirectoryBackofficeCreateRequest, DirectoryBackofficeResponse, DirectoryBackofficeUpdateRequest, TypeOfDirectoryId } from "@fiado/type-kit/bin/directory/index.js";
+import type { DirectoryAgentsBySponsorResponse } from "@fiado/type-kit/bin/directory/index.js";
 /**
  * Interfaz para el servicio Directory que permite operaciones sobre directorios.
  */
@@ -28,5 +29,10 @@ export interface IDirectoriesApi {
      * Borra físicamente el directorio de agente (DirectoryAgents_GT) por su sponsorDirectoryId.
      */
     deleteAgentBySponsorDirectoryId(sponsorDirectoryId: string): Promise<FiadoApiResponse<any>>;
+    /**
+     * POST directories/search/by-sponsor-directory-ids: directorio AGENT ganador por sponsor, en lotes de 100.
+     * Devuelve el mapa ya desempaquetado de `.data`; lanza el error del http sin fallback.
+     */
+    getAgentDirectoriesBySponsorDirectoryIds(sponsorDirectoryIds: string[]): Promise<DirectoryAgentsBySponsorResponse>;
 }
 export {};

package/bin/platformRbac/api/PlatformRbacBusinessApi.d.ts

@@ -1,6 +1,7 @@
 import type { IHttpRequest } from "@fiado/http-client";
 import { APIGatewayProxyResultBody, ApiGatewayResponse, ResolvedPermissions, ResolveInput } from "@fiado/gateway-adapter";
 import { DefineNextChallengeRequest, DefineNextChallengeResponse, PrepareChallengeRequest, PrepareChallengeResponse, VerifyChallengeRequest, VerifyChallengeResponse, AuthorizeRequest, AuthorizeResponse, EffectivePermissionsResponse, InjectableUserAttributesResponse, PermissionScope, CreateLevelEntityRequest, CreateLevelEntityResponse, CreateTenantUserRequest, CreateTenantUserResponse, UserProfileResponse, ListLevelEntitiesResponse, LevelEntityResponse, UpdateLevelEntityRequest, DeleteLevelEntityRequest, DeleteLevelEntityResponse, ListTenantUsersResponse, GetTenantUserResponse, TenantUserResponse, TenantUserAckResponse, UpdateTenantUserRequest, DeleteTenantUserRequest, DisableTenantUserRequest, EnableTenantUserRequest, ResetTenantUserPasswordRequest, ResetTenantUserPasswordResponse, ResetTenantUserMfaRequest, ListTenantRolesResponse, AssignTenantRoleRequest, AssignTenantRoleResponse, RevokeTenantRoleRequest, RevokeTenantRoleResponse } from "@fiado/type-kit/bin/platformRbac/index.js";
+import type { TenantUsersBySubsResponse } from "@fiado/type-kit/bin/platformRbac/index.js";
 import { IPlatformRbacBusinessApi } from "./interfaces/IPlatformRbacBusinessApi.js";
 /**
  * Publisher HTTP del lambda `platform-rbac-business` (componente 06 SureKeep Fase 0)
@@ -76,4 +77,6 @@ export default class PlatformRbacBusinessApi implements IPlatformRbacBusinessApi
      * El `cognitoSub` va en el cuerpo porque es parte de la llave de la tabla de asignaciones.
      */
     revokeTenantRole(tenantId: string, assignmentId: string, input: RevokeTenantRoleRequest): Promise<APIGatewayProxyResultBody<RevokeTenantRoleResponse>>;
+    /** POST /internal/tenants/{tenantId}/users/by-subs — usuarios del tenant por cognitoSub, en lotes de 100; devuelve el mapa de `.data`. */
+    getTenantUsersBySubs(tenantId: string, cognitoSubs: string[]): Promise<TenantUsersBySubsResponse>;
 }

package/bin/platformRbac/api/PlatformRbacBusinessApi.js

@@ -11,6 +11,10 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
     return function (target, key) { decorator(target, key, paramIndex); }
 };
 import { inject, injectable } from "inversify";
+// TD-AI-003: el tipo de retorno de los métodos viejos no refleja el runtime. Ver docs/TECH_DEBT.md.
+import { TENANT_USERS_BY_SUBS_MAX_BATCH, } from "@fiado/type-kit/bin/platformRbac/index.js";
+import { joinUrl } from "../../utils/joinUrl.js";
+import { postIdsInBatches } from "../../utils/postIdsInBatches.js";
 /**
  * Publisher HTTP del lambda `platform-rbac-business` (componente 06 SureKeep Fase 0)
  * para los 3 endpoints internos del Custom Auth Challenge flow.
@@ -185,6 +189,11 @@ let PlatformRbacBusinessApi = class PlatformRbacBusinessApi {
         const url = `${this.baseUrl}/internal/tenants/${encodeURIComponent(tenantId)}/role-assignments/${encodeURIComponent(assignmentId)}/revoke`;
         return await this.httpRequest.post(url, input);
     }
+    /** POST /internal/tenants/{tenantId}/users/by-subs — usuarios del tenant por cognitoSub, en lotes de 100; devuelve el mapa de `.data`. */
+    async getTenantUsersBySubs(tenantId, cognitoSubs) {
+        const url = joinUrl(this.baseUrl, `internal/tenants/${encodeURIComponent(tenantId)}/users/by-subs`);
+        return await postIdsInBatches(this.httpRequest, url, "cognitoSubs", cognitoSubs, TENANT_USERS_BY_SUBS_MAX_BATCH);
+    }
 };
 PlatformRbacBusinessApi = __decorate([
     injectable(),

package/bin/platformRbac/api/interfaces/IPlatformRbacBusinessApi.d.ts

@@ -1,5 +1,6 @@
 import { APIGatewayProxyResultBody, ApiGatewayResponse, ResolvedPermissions, ResolveInput } from "@fiado/gateway-adapter";
 import { DefineNextChallengeRequest, DefineNextChallengeResponse, PrepareChallengeRequest, PrepareChallengeResponse, VerifyChallengeRequest, VerifyChallengeResponse, AuthorizeRequest, AuthorizeResponse, EffectivePermissionsResponse, InjectableUserAttributesResponse, PermissionScope, CreateLevelEntityRequest, CreateLevelEntityResponse, CreateTenantUserRequest, CreateTenantUserResponse, UserProfileResponse, ListLevelEntitiesResponse, LevelEntityResponse, UpdateLevelEntityRequest, DeleteLevelEntityRequest, DeleteLevelEntityResponse, ListTenantUsersResponse, GetTenantUserResponse, TenantUserResponse, TenantUserAckResponse, UpdateTenantUserRequest, DeleteTenantUserRequest, DisableTenantUserRequest, EnableTenantUserRequest, ResetTenantUserPasswordRequest, ResetTenantUserPasswordResponse, ResetTenantUserMfaRequest, ListTenantRolesResponse, AssignTenantRoleRequest, AssignTenantRoleResponse, RevokeTenantRoleRequest, RevokeTenantRoleResponse } from "@fiado/type-kit/bin/platformRbac/index.js";
+import type { TenantUsersBySubsResponse } from "@fiado/type-kit/bin/platformRbac/index.js";
 /**
  * Contrato del publisher HTTP del lambda `platform-rbac-business` (componente 06 SureKeep Fase 0)
  * para los 3 endpoints internos del Custom Auth Challenge flow (MFA).
@@ -120,4 +121,9 @@ export interface IPlatformRbacBusinessApi {
      * El `cognitoSub` va en el cuerpo porque es parte de la llave de la tabla de asignaciones.
      */
     revokeTenantRole(tenantId: string, assignmentId: string, input: RevokeTenantRoleRequest): Promise<APIGatewayProxyResultBody<RevokeTenantRoleResponse>>;
+    /**
+     * POST /internal/tenants/{tenantId}/users/by-subs — usuarios del tenant por cognitoSub, en lotes de 100.
+     * Devuelve el mapa ya desempaquetado de `.data`; lanza el error del http sin fallback.
+     */
+    getTenantUsersBySubs(tenantId: string, cognitoSubs: string[]): Promise<TenantUsersBySubsResponse>;
 }

package/bin/referral-business/ReferralBusinessApi.d.ts

@@ -1,7 +1,8 @@
-import { IHttpRequest } from "@fiado/http-client";
+import type { IHttpRequest } from "@fiado/http-client";
 import { IReferralBusinessApi } from "./interfaces/IReferralBusinessApi.js";
 type FiadoApiResponse<T> = import("@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js").default<T>;
 import { Scope } from "@fiado/type-kit/bin/directory/enums/Scope.js";
+import type { AgentsByDirectoryIdsResponse } from "@fiado/type-kit/bin/referral-business/index.js";
 export declare class ReferralBusinessApi implements IReferralBusinessApi {
     private httpRequest;
     private readonly baseUrl;
@@ -22,5 +23,6 @@ export declare class ReferralBusinessApi implements IReferralBusinessApi {
     getByDirectoryId(directoryId: string): Promise<FiadoApiResponse<any>>;
     accountOpeningsBySponsor(newDirectoryId: string, scope: Scope): Promise<FiadoApiResponse<any>>;
     deleteAgent(directoryId: string): Promise<FiadoApiResponse<any>>;
+    getAgentsByDirectoryIds(directoryIds: string[]): Promise<AgentsByDirectoryIdsResponse>;
 }
 export {};

package/bin/referral-business/ReferralBusinessApi.js

@@ -12,6 +12,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 };
 import { inject, injectable } from "inversify";
 import dotenv from 'dotenv';
+import { AGENTS_BY_DIRECTORY_IDS_MAX_BATCH } from "@fiado/type-kit/bin/referral-business/index.js";
+import { joinUrl } from "../utils/joinUrl.js";
+import { postIdsInBatches } from "../utils/postIdsInBatches.js";
 dotenv.config();
 let ReferralBusinessApi = class ReferralBusinessApi {
     httpRequest;
@@ -39,6 +42,10 @@ let ReferralBusinessApi = class ReferralBusinessApi {
         const url = `${this.baseUrl}backoffice/agents/directory/${directoryId}`;
         return await this.httpRequest.delete(url);
     }
+    async getAgentsByDirectoryIds(directoryIds) {
+        const url = joinUrl(this.baseUrl, "private/agents/by-directory-ids");
+        return await postIdsInBatches(this.httpRequest, url, "directoryIds", directoryIds, AGENTS_BY_DIRECTORY_IDS_MAX_BATCH);
+    }
 };
 ReferralBusinessApi = __decorate([
     injectable(),

package/bin/referral-business/interfaces/IReferralBusinessApi.d.ts

@@ -1,5 +1,6 @@
 type FiadoApiResponse<T> = import("@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js").default<T>;
 import { Scope } from "@fiado/type-kit/bin/directory/enums/Scope.js";
+import type { AgentsByDirectoryIdsResponse } from "@fiado/type-kit/bin/referral-business/index.js";
 /**
  * Interfaz para el servicio Payroll que permite operaciones sobre payroll.
  */
@@ -46,5 +47,10 @@ export interface IReferralBusinessApi {
      * @throws {Error} Lanza un error si los parámetros de entrada son inválidos.
      */
     deleteAgent(directoryId: string): Promise<FiadoApiResponse<any>>;
+    /**
+     * POST private/agents/by-directory-ids: fila ganadora de Agents_GT por directorio, en lotes de 100.
+     * Devuelve el mapa ya desempaquetado de `.data`; lanza el error del http sin fallback.
+     */
+    getAgentsByDirectoryIds(directoryIds: string[]): Promise<AgentsByDirectoryIdsResponse>;
 }
 export {};

package/bin/utils/postIdsInBatches.d.ts

@@ -0,0 +1,2 @@
+import type { IHttpRequest } from "@fiado/http-client";
+export declare function postIdsInBatches<TItem>(httpRequest: IHttpRequest, url: string, bodyKey: string, ids: string[], maxBatch: number): Promise<Record<string, TItem>>;

package/bin/utils/postIdsInBatches.js

@@ -0,0 +1,22 @@
+// Deduplica y descarta ids vacíos, hace un POST por lote de `maxBatch` y fusiona los mapas de `.data`.
+// Lista vacía devuelve {} sin llamar; un error del http se propaga sin fallback.
+export async function postIdsInBatches(httpRequest, url, bodyKey, ids, maxBatch) {
+    const uniqueIds = Array.from(new Set(ids.filter((id) => typeof id === "string" && id.length > 0)));
+    const merged = {};
+    for (let i = 0; i < uniqueIds.length; i += maxBatch) {
+        const batch = uniqueIds.slice(i, i + maxBatch);
+        const response = await httpRequest.post(url, { [bodyKey]: batch });
+        Object.assign(merged, unwrapBatchMap(response, url));
+    }
+    return merged;
+}
+// Sin `.data` es un lote sin resultados; un `.data` que no es mapa es un error del contrato.
+function unwrapBatchMap(response, url) {
+    const data = response?.data;
+    if (data === undefined || data === null)
+        return {};
+    if (typeof data !== "object" || Array.isArray(data)) {
+        throw new Error(`La respuesta batch de ${url} no trae un mapa en .data`);
+    }
+    return data;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiado/api-invoker",
-  "version": "5.94.0",
+  "version": "5.96.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.465.0",
+    "@fiado/type-kit": "^3.468.0",
     "dotenv": "^16.4.7"
   },
   "peerDependencies": {

package/src/directories/DirectoriesApi.ts

@@ -1,8 +1,11 @@
 import dotenv from 'dotenv';
 import { inject, injectable } from "inversify";
-import { IHttpRequest } from "@fiado/http-client";
+import type { IHttpRequest } from "@fiado/http-client";
 import { IDirectoriesApi } from "./interfaces/IDirectoriesApi.js";
-import { DirectoryBackofficeResponse, DirectoryBackofficeCreateRequest, DirectoryBackofficeUpdateRequest, TypeOfDirectoryId } from '@fiado/type-kit/bin/directory/index.js';
+import { DirectoryBackofficeResponse, DirectoryBackofficeCreateRequest, DirectoryBackofficeUpdateRequest, TypeOfDirectoryId, DIRECTORY_AGENTS_BY_SPONSOR_MAX_BATCH } from '@fiado/type-kit/bin/directory/index.js';
+import type { DirectoryAgentBySponsorItem, DirectoryAgentsBySponsorResponse } from '@fiado/type-kit/bin/directory/index.js';
+import { joinUrl } from "../utils/joinUrl.js";
+import { postIdsInBatches } from "../utils/postIdsInBatches.js";
 type FiadoApiResponse<T> = import('@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js').default<T>;
 dotenv.config();
 
@@ -65,4 +68,11 @@ export class DirectoriesApi implements IDirectoriesApi {
         const url: string = `${this.baseUrl}directories/backoffice/${directoryId}`;
         return await this.httpRequest.put(url, params);
     }
+
+    async getAgentDirectoriesBySponsorDirectoryIds(sponsorDirectoryIds: string[]): Promise<DirectoryAgentsBySponsorResponse> {
+        const url = joinUrl(this.baseUrl, "directories/search/by-sponsor-directory-ids");
+        return await postIdsInBatches<DirectoryAgentBySponsorItem>(
+            this.httpRequest, url, "sponsorDirectoryIds", sponsorDirectoryIds, DIRECTORY_AGENTS_BY_SPONSOR_MAX_BATCH,
+        );
+    }
 }

package/src/directories/interfaces/IDirectoriesApi.ts

@@ -1,5 +1,6 @@
 type FiadoApiResponse<T> = import('@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js').default<T>;
 import { DirectoryBackofficeCreateRequest, DirectoryBackofficeResponse, DirectoryBackofficeUpdateRequest, TypeOfDirectoryId } from "@fiado/type-kit/bin/directory/index.js";
+import type { DirectoryAgentsBySponsorResponse } from "@fiado/type-kit/bin/directory/index.js";
 
 /**
  * Interfaz para el servicio Directory que permite operaciones sobre directorios.
@@ -18,4 +19,9 @@ export interface IDirectoriesApi {
      * Borra físicamente el directorio de agente (DirectoryAgents_GT) por su sponsorDirectoryId.
      */
     deleteAgentBySponsorDirectoryId(sponsorDirectoryId: string): Promise<FiadoApiResponse<any>>;
+    /**
+     * POST directories/search/by-sponsor-directory-ids: directorio AGENT ganador por sponsor, en lotes de 100.
+     * Devuelve el mapa ya desempaquetado de `.data`; lanza el error del http sin fallback.
+     */
+    getAgentDirectoriesBySponsorDirectoryIds(sponsorDirectoryIds: string[]): Promise<DirectoryAgentsBySponsorResponse>;
 }

package/src/platformRbac/api/PlatformRbacBusinessApi.ts

@@ -45,8 +45,12 @@ import {
     AssignTenantRoleResponse,
     RevokeTenantRoleRequest,
     RevokeTenantRoleResponse,
+    TENANT_USERS_BY_SUBS_MAX_BATCH,
 } from "@fiado/type-kit/bin/platformRbac/index.js";
+import type { TenantUserBySubItem, TenantUsersBySubsResponse } from "@fiado/type-kit/bin/platformRbac/index.js";
 import { IPlatformRbacBusinessApi } from "./interfaces/IPlatformRbacBusinessApi.js";
+import { joinUrl } from "../../utils/joinUrl.js";
+import { postIdsInBatches } from "../../utils/postIdsInBatches.js";
 
 /**
  * Publisher HTTP del lambda `platform-rbac-business` (componente 06 SureKeep Fase 0)
@@ -333,4 +337,12 @@ export default class PlatformRbacBusinessApi implements IPlatformRbacBusinessApi
         const url = `${this.baseUrl}/internal/tenants/${encodeURIComponent(tenantId)}/role-assignments/${encodeURIComponent(assignmentId)}/revoke`;
         return await this.httpRequest.post(url, input);
     }
+
+    /** POST /internal/tenants/{tenantId}/users/by-subs — usuarios del tenant por cognitoSub, en lotes de 100; devuelve el mapa de `.data`. */
+    async getTenantUsersBySubs(tenantId: string, cognitoSubs: string[]): Promise<TenantUsersBySubsResponse> {
+        const url = joinUrl(this.baseUrl, `internal/tenants/${encodeURIComponent(tenantId)}/users/by-subs`);
+        return await postIdsInBatches<TenantUserBySubItem>(
+            this.httpRequest, url, "cognitoSubs", cognitoSubs, TENANT_USERS_BY_SUBS_MAX_BATCH,
+        );
+    }
 }

package/src/platformRbac/api/interfaces/IPlatformRbacBusinessApi.ts

@@ -43,6 +43,7 @@ import {
     RevokeTenantRoleRequest,
     RevokeTenantRoleResponse,
 } from "@fiado/type-kit/bin/platformRbac/index.js";
+import type { TenantUsersBySubsResponse } from "@fiado/type-kit/bin/platformRbac/index.js";
 
 /**
  * Contrato del publisher HTTP del lambda `platform-rbac-business` (componente 06 SureKeep Fase 0)
@@ -273,4 +274,10 @@ export interface IPlatformRbacBusinessApi {
         assignmentId: string,
         input: RevokeTenantRoleRequest,
     ): Promise<APIGatewayProxyResultBody<RevokeTenantRoleResponse>>;
+
+    /**
+     * POST /internal/tenants/{tenantId}/users/by-subs — usuarios del tenant por cognitoSub, en lotes de 100.
+     * Devuelve el mapa ya desempaquetado de `.data`; lanza el error del http sin fallback.
+     */
+    getTenantUsersBySubs(tenantId: string, cognitoSubs: string[]): Promise<TenantUsersBySubsResponse>;
 }

package/src/referral-business/ReferralBusinessApi.ts

@@ -1,9 +1,13 @@
 import { inject, injectable } from "inversify";
-import { IHttpRequest } from "@fiado/http-client";
+import type { IHttpRequest } from "@fiado/http-client";
 import dotenv from 'dotenv';
 import { IReferralBusinessApi } from "./interfaces/IReferralBusinessApi.js";
 type FiadoApiResponse<T> = import("@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js").default<T>;
 import { Scope } from "@fiado/type-kit/bin/directory/enums/Scope.js";
+import { AGENTS_BY_DIRECTORY_IDS_MAX_BATCH } from "@fiado/type-kit/bin/referral-business/index.js";
+import type { AgentByDirectoryIdItem, AgentsByDirectoryIdsResponse } from "@fiado/type-kit/bin/referral-business/index.js";
+import { joinUrl } from "../utils/joinUrl.js";
+import { postIdsInBatches } from "../utils/postIdsInBatches.js";
 
 dotenv.config();
 
@@ -40,4 +44,11 @@ export class ReferralBusinessApi implements IReferralBusinessApi {
         const url = `${this.baseUrl}backoffice/agents/directory/${directoryId}`;
         return await this.httpRequest.delete(url);
     }
+
+    async getAgentsByDirectoryIds(directoryIds: string[]): Promise<AgentsByDirectoryIdsResponse> {
+        const url = joinUrl(this.baseUrl, "private/agents/by-directory-ids");
+        return await postIdsInBatches<AgentByDirectoryIdItem>(
+            this.httpRequest, url, "directoryIds", directoryIds, AGENTS_BY_DIRECTORY_IDS_MAX_BATCH,
+        );
+    }
 }

package/src/referral-business/interfaces/IReferralBusinessApi.ts

@@ -1,5 +1,6 @@
 type FiadoApiResponse<T> = import("@fiado/type-kit/bin/apiResponse/dtos/FiadoApiResponse.js").default<T>;
 import { Scope } from "@fiado/type-kit/bin/directory/enums/Scope.js";
+import type { AgentsByDirectoryIdsResponse } from "@fiado/type-kit/bin/referral-business/index.js";
 
 /**
  * Interfaz para el servicio Payroll que permite operaciones sobre payroll.
@@ -42,4 +43,10 @@ export interface IReferralBusinessApi {
      * @throws {Error} Lanza un error si los parámetros de entrada son inválidos.
      */
     deleteAgent(directoryId: string): Promise<FiadoApiResponse<any>>;
+
+    /**
+     * POST private/agents/by-directory-ids: fila ganadora de Agents_GT por directorio, en lotes de 100.
+     * Devuelve el mapa ya desempaquetado de `.data`; lanza el error del http sin fallback.
+     */
+    getAgentsByDirectoryIds(directoryIds: string[]): Promise<AgentsByDirectoryIdsResponse>;
 }

package/src/utils/postIdsInBatches.ts

@@ -0,0 +1,40 @@
+import type { IHttpRequest } from "@fiado/http-client";
+
+// Envelope Fiado de las respuestas batch: el mapa viaja en `.data`.
+interface BatchMapEnvelope<TItem> {
+    data?: Record<string, TItem> | null;
+}
+
+// Deduplica y descarta ids vacíos, hace un POST por lote de `maxBatch` y fusiona los mapas de `.data`.
+// Lista vacía devuelve {} sin llamar; un error del http se propaga sin fallback.
+export async function postIdsInBatches<TItem>(
+    httpRequest: IHttpRequest,
+    url: string,
+    bodyKey: string,
+    ids: string[],
+    maxBatch: number,
+): Promise<Record<string, TItem>> {
+    const uniqueIds = Array.from(new Set(ids.filter((id) => typeof id === "string" && id.length > 0)));
+    const merged: Record<string, TItem> = {};
+
+    for (let i = 0; i < uniqueIds.length; i += maxBatch) {
+        const batch = uniqueIds.slice(i, i + maxBatch);
+        const response = await httpRequest.post<BatchMapEnvelope<TItem>>(url, { [bodyKey]: batch });
+        Object.assign(merged, unwrapBatchMap(response, url));
+    }
+
+    return merged;
+}
+
+// Sin `.data` es un lote sin resultados; un `.data` que no es mapa es un error del contrato.
+function unwrapBatchMap<TItem>(
+    response: BatchMapEnvelope<TItem> | null | undefined,
+    url: string,
+): Record<string, TItem> {
+    const data = response?.data;
+    if (data === undefined || data === null) return {};
+    if (typeof data !== "object" || Array.isArray(data)) {
+        throw new Error(`La respuesta batch de ${url} no trae un mapa en .data`);
+    }
+    return data;
+}