@fiado/api-invoker 4.3.0 → 4.5.0

package/README.md

@@ -1,600 +1,600 @@
-<div align="center">
-
-# 🔗 Fiado API Invoker
-
-### Librería de Comunicación Inter-Servicios para Microservicios Lambda
-
-[![npm](https://img.shields.io/badge/npm-@fiado/api--invoker-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![AWS Lambda](https://img.shields.io/badge/AWS-Lambda-FF9900?logo=aws-lambda&logoColor=white)](https://aws.amazon.com/lambda/)
-[![InversifyJS](https://img.shields.io/badge/InversifyJS-6.x-1E88E5)](https://inversify.io/)
-
-</div>
-
----
-
-## Tabla de Contenidos
-
-- [Descripción General](#descripción-general)
-- [Arquitectura](#arquitectura)
-- [Instalación](#instalación)
-- [Configuración](#configuración)
-- [APIs Disponibles](#apis-disponibles)
-- [Publishers (Colas SQS)](#publishers-colas-sqs)
-- [Uso en Proyectos](#uso-en-proyectos)
-- [Variables de Entorno](#variables-de-entorno)
-- [Estructura del Proyecto](#estructura-del-proyecto)
-- [Convenciones de Desarrollo](#convenciones-de-desarrollo)
-- [Dependencias](#dependencias)
-
----
-
-## Descripción General
-
-`@fiado/api-invoker` es una librería empresarial que actúa como **puente de comunicación entre microservicios Lambda** dentro del ecosistema Fiado. Proporciona:
-
-- **Clientes HTTP tipados** para invocar APIs privadas de otros Lambdas
-- **Publishers SQS** para comunicación asíncrona mediante colas
-- **Inyección de dependencias** integrada con InversifyJS
-- **Abstracción de complejidad** de configuración y manejo de errores
-
-### Propósito
-
-En una arquitectura de microservicios, cada Lambda expone una API privada accesible únicamente desde la VPC. Esta librería encapsula:
-
-1. La construcción de URLs base desde variables de entorno
-2. El manejo de headers y operaciones HTTP
-3. La serialización/deserialización de payloads
-4. La publicación de mensajes a colas SQS
-
----
-
-## Arquitectura
-
-```
-┌─────────────────────────────────────────────────────────────────────────┐
-│                         LAMBDA CONSUMIDOR                                │
-│                                                                          │
-│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐  │
-│  │   Manager/       │───▶│  @fiado/         │───▶│  @fiado/         │  │
-│  │   Service        │    │  api-invoker     │    │  http-client     │  │
-│  └──────────────────┘    └──────────────────┘    └──────────────────┘  │
-│                                   │                        │            │
-└───────────────────────────────────┼────────────────────────┼────────────┘
-                                    │                        │
-                    ┌───────────────┴───────────────┐        │
-                    ▼                               ▼        ▼
-            ┌──────────────┐                ┌──────────────────┐
-            │   AWS SQS    │                │  API Gateway     │
-            │   (Queues)   │                │  (Private VPC)   │
-            └──────────────┘                └──────────────────┘
-                    │                               │
-                    ▼                               ▼
-            ┌──────────────┐                ┌──────────────────┐
-            │   Lambda     │                │   Lambda         │
-            │   Subscriber │                │   Target         │
-            └──────────────┘                └──────────────────┘
-```
-
-### Patrones de Comunicación
-
-| Patrón | Implementación | Uso |
-|--------|----------------|-----|
-| **Síncrono** | HTTP via API Gateway privado | Consultas, operaciones CRUD |
-| **Asíncrono** | SQS Publishers | Eventos, notificaciones, procesos batch |
-
----
-
-## Instalación
-
-```bash
-npm install @fiado/api-invoker @fiado/http-client
-```
-
-### Peer Dependencies
-
-La librería requiere las siguientes dependencias en el proyecto consumidor:
-
-```json
-{
-  "@fiado/http-client": "^1.0.7",
-  "@fiado/logger": "^1.0.3",
-  "@fiado/type-kit": "^2.1.28",
-  "inversify": "^6.2.2",
-  "reflect-metadata": "^0.2.2"
-}
-```
-
----
-
-## Configuración
-
-### Registro en el Contenedor IoC
-
-La librería exporta un `ContainerModule` de InversifyJS que registra automáticamente todos los clientes API y publishers:
-
-```typescript
-import { Container } from "inversify";
-import { IHttpRequest, AxiosHttpRequest } from "@fiado/http-client";
-import { apiInvokerBindings } from "@fiado/api-invoker";
-
-const container = new Container();
-
-// 1. Cargar bindings de api-invoker (registra todos los clientes)
-container.load(apiInvokerBindings);
-
-// 2. Registrar el cliente HTTP (requerido por los clientes API)
-container.bind<IHttpRequest>("IHttpRequest").to(AxiosHttpRequest);
-
-export { container };
-```
-
-### Importación de Interfaces
-
-```typescript
-// Importar interfaces específicas
-import { 
-    IDirectoryApi, 
-    IIdentityApi, 
-    ITransactionApi,
-    INotificationMessagesPublisher 
-} from "@fiado/api-invoker";
-```
-
----
-
-## APIs Disponibles
-
-La librería proporciona clientes para **60+ microservicios** del ecosistema Fiado:
-
-### Servicios Core
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `IDirectoryApi` | Gestión de directorios de usuarios | `DIRECTORY_LAMBDA_URL` |
-| `IIdentityApi` | Verificación de identidad | `IDENTITY_LAMBDA_URL` |
-| `IAuthenticationApi` | Autenticación y tokens | `AUTHENTICATION_LAMBDA_URL` |
-| `ITransactionApi` | Procesamiento de transacciones | `TRANSACTION_LAMBDA_URL` |
-
-### Servicios de Cuenta
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `IAccountFiadoIncApi` | Cuentas Fiado Inc | `ACCOUNT_FIADOINC_LAMBDA_URL` |
-| `IAccountFiadoSAApi` | Cuentas Fiado SA | `ACCOUNT_FIADOSA_LAMBDA_URL` |
-| `IAccountPagoConfiadoApi` | Cuentas PagoConfiado | `ACCOUNT_PAGOCONFIADO_LAMBDA_URL` |
-| `IAccountBeneficiaryApi` | Beneficiarios de cuentas | `ACCOUNT_BENEFICIARY_LAMBDA_URL` |
-| `IBankAccountApi` | Cuentas bancarias | `BANK_ACCOUNT_LAMBDA_URL` |
-
-### Servicios de Pago
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `IStpSpeiApi` | Transferencias SPEI | `STP_SPEI_LAMBDA_URL` |
-| `IStpServicePaymentApi` | Pagos de servicios STP | `STP_SERVICE_PAYMENT_LAMBDA_URL` |
-| `ICentralPaymentsConnectorApi` | Conector de pagos central | `CENTRAL_PAYMENTS_LAMBDA_URL` |
-| `ICollectorApi` | Cobranza | `COLLECTOR_LAMBDA_URL` |
-
-### Servicios de Tarjeta
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `ICardApi` | Gestión de tarjetas | `CARD_LAMBDA_URL` |
-| `IPomeloApi` | Integración Pomelo | `POMELO_LAMBDA_URL` |
-| `IPomeloProcessorApi` | Procesador Pomelo | `POMELO_PROCESSOR_LAMBDA_URL` |
-
-### Servicios de Riesgo y Fraude
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `IRiskProfileApi` | Perfiles de riesgo | `RISK_PROFILE_LAMBDA_URL` |
-| `IFraudPreventionEngineApi` | Motor antifraude | `FRAUD_PREVENTION_LAMBDA_URL` |
-| `IBlackListApi` | Listas negras | `BLACKLIST_LAMBDA_URL` |
-| `ITransactionAlertApi` | Alertas de transacciones | `RISK_PROFILE_LAMBDA_URL` |
-
-### Servicios de Onboarding
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `IOnboardingApi` | Onboarding de usuarios | `ONBOARDING_LAMBDA_URL` |
-| `IOnboardingBusinessApi` | Onboarding de negocios | `ONBOARDING_BUSINESS_LAMBDA_URL` |
-| `ICnbvApi` | Integración CNBV | `CNBV_BUSINESS_LAMBDA_URL` |
-
-### Servicios de Comunicación
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `IFiadoMessagesApi` | Mensajería interna | `FIADO_MESSAGES_LAMBDA_URL` |
-| `IFirebaseConnectorApi` | Push notifications | `FIREBASE_CONNECTOR_LAMBDA_URL` |
-| `IZendeskApi` | Integración Zendesk | `ZENDESK_LAMBDA_URL` |
-
-### Servicios de Negocio
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `IActivityApi` | Actividades de negocio | `ACTIVITY_BUSINESS_LAMBDA_URL` |
-| `IServiceApi` | Servicios de negocio | `SERVICE_BUSINESS_LAMBDA_URL` |
-| `IPriceListApi` | Listas de precios | `PRICELIST_BUSINESS_LAMBDA_URL` |
-| `IPayrollApi` | Nómina | `PAYROLL_BUSINESS_LAMBDA_URL` |
-| `IOrderCollectorApi` | Órdenes de cobranza | `ORDER_COLLECTOR_LAMBDA_URL` |
-
-### Servicios Auxiliares
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `IAddressApi` | Direcciones | `ADDRESS_LAMBDA_URL` |
-| `IContactInformationApi` | Información de contacto | `CONTACT_INFORMATION_LAMBDA_URL` |
-| `IDeviceApi` | Dispositivos | `DEVICE_LAMBDA_URL` |
-| `IGroupApi` | Grupos | `GROUP_LAMBDA_URL` |
-| `IP2pContactApi` | Contactos P2P | `P2P_CONTACT_LAMBDA_URL` |
-| `IExchangeRatesApi` | Tipos de cambio | `EXCHANGE_RATES_LAMBDA_URL` |
-| `IProductCatalogApi` | Catálogo de productos | `PRODUCT_CATALOG_LAMBDA_URL` |
-| `IContractGeneratorApi` | Generador de contratos | `CONTRACT_GENERATOR_LAMBDA_URL` |
-| `IDocumentImageProcessorApi` | Procesador de imágenes | `DOCUMENT_IMAGE_PROCESSOR_LAMBDA_URL` |
-| `ILegalDocumentApi` | Documentos legales | `LEGAL_DOCUMENT_LAMBDA_URL` |
-| `IObservationsApi` | Observaciones | `OBSERVATIONS_LAMBDA_URL` |
-| `IDirectoriesApi` | Directorios múltiples | `DIRECTORIES_LAMBDA_URL` |
-| `IDirectorySettingApi` | Configuración de directorio | `DIRECTORY_SETTING_LAMBDA_URL` |
-| `IAppSelectionDataApi` | Datos de selección de app | `APP_SELECTION_DATA_LAMBDA_URL` |
-| `IReferralBusinessApi` | Referidos | `REFERRAL_BUSINESS_LAMBDA_URL` |
-| `IEventHistoryApi` | Historial de eventos | `EVENT_HISTORY_LAMBDA_URL` |
-| `IReportProcessorBusinessApi` | Procesador de reportes | `REPORT_PROCESSOR_LAMBDA_URL` |
-| `IPeopleBusinessApi` | Gestión de personas | `PEOPLE_BUSINESS_LAMBDA_URL` |
-
-### Integraciones Externas
-
-| Interface | Descripción | Variable de Entorno |
-|-----------|-------------|---------------------|
-| `ITernApi` | Integración Tern | `TERN_LAMBDA_URL` |
-| `IBBVARstApi` | Integración BBVA RST | `BBVA_RST_LAMBDA_URL` |
-| `IEstafetaApi` | Integración Estafeta | `ESTAFETA_LAMBDA_URL` |
-| `ICognitoConnectorApi` | Conector Cognito | `COGNITO_CONNECTOR_LAMBDA_URL` |
-| `ICognitoV2Api` | Cognito V2 | `COGNITO_CONNECTOR_LAMBDA_URL` |
-| `ISTPAccountApi` | Cuentas STP | `STP_ACCOUNT_LAMBDA_URL` |
-
----
-
-## Publishers (Colas SQS)
-
-Para comunicación asíncrona, la librería provee publishers que envían mensajes a colas SQS:
-
-| Interface | Descripción | Variable de Entorno (Queue) |
-|-----------|-------------|----------------------------|
-| `INotificationMessagesPublisher` | Notificaciones push/email/sms | `NOTIFICATION_MESSAGES_QUEUE` |
-| `INotificationWSMessagesPublisher` | Notificaciones WebSocket | `NOTIFICATION_WS_QUEUE` |
-| `ISessionActivityPublisher` | Actividad de sesión | `SESSION_ACTIVITY_QUEUE` |
-| `ITransactionPublisher` | Eventos de transacción | `TRANSACTION_QUEUE` |
-| `IActivityPublisher` | Eventos de actividad | `ACTIVITY_QUEUE` |
-| `ITransactionAlarmPublisher` | Alarmas de transacción | `TRANSACTION_ALARM_QUEUE` |
-| `IPublisher` | Publisher genérico | Configurable |
-
-### Ejemplo de Publisher
-
-```typescript
-import { inject, injectable } from "inversify";
-import { INotificationMessagesPublisher } from "@fiado/api-invoker";
-import { NotificationQueueMessageRequest } from "@fiado/type-kit";
-
-@injectable()
-export class NotificationService {
-    constructor(
-        @inject("INotificationMessagesPublisher") 
-        private notificationPublisher: INotificationMessagesPublisher
-    ) {}
-
-    async sendPushNotification(userId: string, message: string): Promise<void> {
-        const notification: NotificationQueueMessageRequest = {
-            userId,
-            type: "PUSH",
-            message,
-            timestamp: new Date().toISOString()
-        };
-        
-        await this.notificationPublisher.publish(notification);
-    }
-}
-```
-
----
-
-## Uso en Proyectos
-
-### Ejemplo: Consultar Directorio
-
-```typescript
-import { inject, injectable } from "inversify";
-import { IDirectoryApi } from "@fiado/api-invoker";
-import { log } from "@fiado/logger";
-
-@injectable()
-export class UserService {
-    constructor(
-        @inject("IDirectoryApi") private directoryApi: IDirectoryApi
-    ) {}
-
-    async getUsersByIds(directoryIds: string[]): Promise<any[]> {
-        try {
-            const response = await this.directoryApi.getByIds(directoryIds);
-            log.info("Directories fetched successfully", { count: response.length });
-            return response;
-        } catch (error) {
-            log.error("Error fetching directories", error);
-            throw error;
-        }
-    }
-
-    async getUserByPhone(phoneNumber: string): Promise<any> {
-        return await this.directoryApi.getByPhoneNumber(phoneNumber);
-    }
-}
-```
-
-### Ejemplo: Procesar Transacción
-
-```typescript
-import { inject, injectable } from "inversify";
-import { ITransactionApi, ITransactionPublisher } from "@fiado/api-invoker";
-
-@injectable()
-export class PaymentManager {
-    constructor(
-        @inject("ITransactionApi") private transactionApi: ITransactionApi,
-        @inject("ITransactionPublisher") private transactionPublisher: ITransactionPublisher
-    ) {}
-
-    async processPayment(paymentData: any): Promise<void> {
-        // 1. Crear transacción via API síncrona
-        const transaction = await this.transactionApi.create(paymentData);
-        
-        // 2. Publicar evento para procesamiento asíncrono
-        await this.transactionPublisher.publish({
-            transactionId: transaction.id,
-            event: "PAYMENT_INITIATED",
-            timestamp: new Date().toISOString()
-        });
-    }
-}
-```
-
-### Ejemplo: Verificación de Identidad
-
-```typescript
-import { inject, injectable } from "inversify";
-import { IIdentityApi, IRiskProfileApi } from "@fiado/api-invoker";
-
-@injectable()
-export class KYCService {
-    constructor(
-        @inject("IIdentityApi") private identityApi: IIdentityApi,
-        @inject("IRiskProfileApi") private riskProfileApi: IRiskProfileApi
-    ) {}
-
-    async verifyUser(directoryId: string, documents: any): Promise<boolean> {
-        // Verificar identidad
-        const identityResult = await this.identityApi.verify(directoryId, documents);
-        
-        // Evaluar perfil de riesgo
-        const riskProfile = await this.riskProfileApi.evaluate(directoryId);
-        
-        return identityResult.verified && riskProfile.score < 0.5;
-    }
-}
-```
-
----
-
-## Variables de Entorno
-
-Cada cliente API requiere una variable de entorno con la URL base del Lambda destino. El formato estándar es:
-
-```
-{SERVICE_NAME}_LAMBDA_URL=https://{api-id}.execute-api.{region}.amazonaws.com/v1/
-```
-
-### Configuración en template.yml
-
-```yaml
-Environment:
-  Variables:
-    DIRECTORY_LAMBDA_URL: !Sub "{{resolve:ssm:fiado-directory-lambda}}"
-    IDENTITY_LAMBDA_URL: !Sub "{{resolve:ssm:fiado-identity-lambda}}"
-    TRANSACTION_LAMBDA_URL: !Sub "{{resolve:ssm:fiado-transaction-lambda}}"
-    # ... otras URLs
-    
-    # Colas SQS
-    NOTIFICATION_MESSAGES_QUEUE: !ImportValue SqsNotificationMessagesQueueUrl
-    SESSION_ACTIVITY_QUEUE: !ImportValue SqsSessionActivityQueueUrl
-```
-
-### Resolución de URLs
-
-Las URLs se almacenan en **SSM Parameter Store** y se resuelven en tiempo de despliegue. El pipeline de CI/CD registra automáticamente la URL de cada Lambda después del deploy.
-
----
-
-## Estructura del Proyecto
-
-```
-src/
-├── index.ts                    # Exportaciones públicas
-├── container.config.ts         # ContainerModule con todos los bindings
-├── utils/                      # Utilidades compartidas
-│   └── InvokerUtils.ts
-│
-├── directory/                  # Ejemplo de estructura de módulo
-│   ├── index.ts               # Re-exportaciones del módulo
-│   ├── DirectoryApi.ts        # Implementación del cliente
-│   └── interfaces/
-│       └── IDirectoryApi.ts   # Interface del cliente
-│
-├── transaction/               # Módulo con API y Publisher
-│   ├── index.ts
-│   ├── api/
-│   │   ├── TransactionApi.ts
-│   │   └── ITransactionApi.ts
-│   └── queue/
-│       ├── TransactionPublisher.ts
-│       └── ITransactionPublisher.ts
-│
-├── notificationMessages/      # Módulo solo Publisher
-│   ├── index.ts
-│   └── queue/
-│       ├── NotificationMessagePublisher.ts
-│       └── interfaces/
-│           └── INotificationMessagesPublisher.ts
-│
-└── [60+ módulos adicionales...]
-```
-
-### Estructura de un Módulo API
-
-```
-{service-name}/
-├── index.ts                   # export * from './interfaces/I{Service}Api';
-│                              # export * from './{Service}Api';
-├── {Service}Api.ts            # Implementación @injectable()
-└── interfaces/
-    └── I{Service}Api.ts       # Interface con JSDoc
-```
-
-### Estructura de un Módulo con Queue
-
-```
-{service-name}/
-├── index.ts
-├── api/
-│   ├── {Service}Api.ts
-│   └── I{Service}Api.ts
-└── queue/
-    ├── {Service}Publisher.ts
-    └── interfaces/
-        └── I{Service}Publisher.ts
-```
-
----
-
-## Convenciones de Desarrollo
-
-### Nomenclatura
-
-| Elemento | Patrón | Ejemplo |
-|----------|--------|---------|
-| **Carpeta de módulo** | `kebab-case` | `account-fiadoinc/` |
-| **Interface API** | `I{Service}Api` | `IDirectoryApi` |
-| **Implementación API** | `{Service}Api` | `DirectoryApi` |
-| **Interface Publisher** | `I{Service}Publisher` | `ITransactionPublisher` |
-| **Implementación Publisher** | `{Service}Publisher` | `TransactionPublisher` |
-
-### Patrón de Implementación API
-
-```typescript
-import dotenv from 'dotenv';
-import { inject, injectable } from "inversify";
-import { IHttpRequest } from "@fiado/http-client";
-import { I{Service}Api } from "./interfaces/I{Service}Api";
-dotenv.config();
-
-@injectable()
-export class {Service}Api implements I{Service}Api {
-    
-    private readonly baseUrl = process.env.{SERVICE}_LAMBDA_URL || "";
-
-    constructor(
-        @inject("IHttpRequest") private httpRequest: IHttpRequest
-    ) {}
-
-    public async getById(id: string): Promise<any> {
-        const url = `${this.baseUrl}?id=${id}`;
-        const operationName = "getById";
-        
-        return await this.httpRequest.get(url, null, { 
-            'operationName': operationName 
-        });
-    }
-}
-```
-
-### Patrón de Implementación Publisher
-
-```typescript
-import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs";
-import { inject, injectable } from "inversify";
-import { I{Service}Publisher } from "./interfaces/I{Service}Publisher";
-
-@injectable()
-export class {Service}Publisher implements I{Service}Publisher {
-    
-    private readonly queueUrl = process.env.{SERVICE}_QUEUE;
-
-    async publish(message: any): Promise<void> {
-        const client = new SQSClient();
-        const command = new SendMessageCommand({
-            QueueUrl: this.queueUrl,
-            MessageBody: JSON.stringify(message)
-        });
-        await client.send(command);
-    }
-}
-```
-
-### Header operationName
-
-Todas las llamadas HTTP incluyen el header `operationName` que permite:
-- Trazabilidad en logs
-- Métricas por operación
-- Debugging en X-Ray
-
----
-
-## Dependencias
-
-### Runtime
-
-| Dependencia | Versión | Propósito |
-|-------------|---------|-----------|
-| `@aws-sdk/client-sqs` | ^3.919.0 | Cliente SQS para publishers |
-| `@fiado/gateway-adapter` | ^1.1.50 | Tipos de respuesta API |
-| `@fiado/http-client` | ^1.0.7 | Cliente HTTP base |
-| `@fiado/logger` | ^1.0.3 | Logging estructurado |
-| `@fiado/type-kit` | ^2.1.28 | DTOs y tipos compartidos |
-| `inversify` | ^6.2.2 | Inyección de dependencias |
-| `reflect-metadata` | ^0.2.2 | Metadatos para decoradores |
-| `dotenv` | ^16.4.7 | Variables de entorno |
-
-### Desarrollo
-
-| Dependencia | Versión | Propósito |
-|-------------|---------|-----------|
-| `@types/node` | ^20.17.24 | Tipos de Node.js |
-| `typescript` | (peer) | Compilador TypeScript |
-
----
-
-## Compilación y Publicación
-
-### Build
-
-```bash
-npm run build
-```
-
-Genera archivos `.js` y `.d.ts` en el directorio `bin/`.
-
-### Publicación
-
-```bash
-npm version patch|minor|major
-npm publish
-```
-
-La librería se publica en el registry npm privado de Fiado configurado en `.npmrc`.
-
----
-
-<div align="center">
-
-**Fiado Inc.** | @fiado/api-invoker v1.5.34
-
-</div>
-
-
+<div align="center">
+
+# 🔗 Fiado API Invoker
+
+### Librería de Comunicación Inter-Servicios para Microservicios Lambda
+
+[![npm](https://img.shields.io/badge/npm-@fiado/api--invoker-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![AWS Lambda](https://img.shields.io/badge/AWS-Lambda-FF9900?logo=aws-lambda&logoColor=white)](https://aws.amazon.com/lambda/)
+[![InversifyJS](https://img.shields.io/badge/InversifyJS-6.x-1E88E5)](https://inversify.io/)
+
+</div>
+
+---
+
+## Tabla de Contenidos
+
+- [Descripción General](#descripción-general)
+- [Arquitectura](#arquitectura)
+- [Instalación](#instalación)
+- [Configuración](#configuración)
+- [APIs Disponibles](#apis-disponibles)
+- [Publishers (Colas SQS)](#publishers-colas-sqs)
+- [Uso en Proyectos](#uso-en-proyectos)
+- [Variables de Entorno](#variables-de-entorno)
+- [Estructura del Proyecto](#estructura-del-proyecto)
+- [Convenciones de Desarrollo](#convenciones-de-desarrollo)
+- [Dependencias](#dependencias)
+
+---
+
+## Descripción General
+
+`@fiado/api-invoker` es una librería empresarial que actúa como **puente de comunicación entre microservicios Lambda** dentro del ecosistema Fiado. Proporciona:
+
+- **Clientes HTTP tipados** para invocar APIs privadas de otros Lambdas
+- **Publishers SQS** para comunicación asíncrona mediante colas
+- **Inyección de dependencias** integrada con InversifyJS
+- **Abstracción de complejidad** de configuración y manejo de errores
+
+### Propósito
+
+En una arquitectura de microservicios, cada Lambda expone una API privada accesible únicamente desde la VPC. Esta librería encapsula:
+
+1. La construcción de URLs base desde variables de entorno
+2. El manejo de headers y operaciones HTTP
+3. La serialización/deserialización de payloads
+4. La publicación de mensajes a colas SQS
+
+---
+
+## Arquitectura
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         LAMBDA CONSUMIDOR                                │
+│                                                                          │
+│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐  │
+│  │   Manager/       │───▶│  @fiado/         │───▶│  @fiado/         │  │
+│  │   Service        │    │  api-invoker     │    │  http-client     │  │
+│  └──────────────────┘    └──────────────────┘    └──────────────────┘  │
+│                                   │                        │            │
+└───────────────────────────────────┼────────────────────────┼────────────┘
+                                    │                        │
+                    ┌───────────────┴───────────────┐        │
+                    ▼                               ▼        ▼
+            ┌──────────────┐                ┌──────────────────┐
+            │   AWS SQS    │                │  API Gateway     │
+            │   (Queues)   │                │  (Private VPC)   │
+            └──────────────┘                └──────────────────┘
+                    │                               │
+                    ▼                               ▼
+            ┌──────────────┐                ┌──────────────────┐
+            │   Lambda     │                │   Lambda         │
+            │   Subscriber │                │   Target         │
+            └──────────────┘                └──────────────────┘
+```
+
+### Patrones de Comunicación
+
+| Patrón | Implementación | Uso |
+|--------|----------------|-----|
+| **Síncrono** | HTTP via API Gateway privado | Consultas, operaciones CRUD |
+| **Asíncrono** | SQS Publishers | Eventos, notificaciones, procesos batch |
+
+---
+
+## Instalación
+
+```bash
+npm install @fiado/api-invoker @fiado/http-client
+```
+
+### Peer Dependencies
+
+La librería requiere las siguientes dependencias en el proyecto consumidor:
+
+```json
+{
+  "@fiado/http-client": "^1.0.7",
+  "@fiado/logger": "^1.0.3",
+  "@fiado/type-kit": "^2.1.28",
+  "inversify": "^6.2.2",
+  "reflect-metadata": "^0.2.2"
+}
+```
+
+---
+
+## Configuración
+
+### Registro en el Contenedor IoC
+
+La librería exporta un `ContainerModule` de InversifyJS que registra automáticamente todos los clientes API y publishers:
+
+```typescript
+import { Container } from "inversify";
+import { IHttpRequest, AxiosHttpRequest } from "@fiado/http-client";
+import { apiInvokerBindings } from "@fiado/api-invoker";
+
+const container = new Container();
+
+// 1. Cargar bindings de api-invoker (registra todos los clientes)
+container.load(apiInvokerBindings);
+
+// 2. Registrar el cliente HTTP (requerido por los clientes API)
+container.bind<IHttpRequest>("IHttpRequest").to(AxiosHttpRequest);
+
+export { container };
+```
+
+### Importación de Interfaces
+
+```typescript
+// Importar interfaces específicas
+import { 
+    IDirectoryApi, 
+    IIdentityApi, 
+    ITransactionApi,
+    INotificationMessagesPublisher 
+} from "@fiado/api-invoker";
+```
+
+---
+
+## APIs Disponibles
+
+La librería proporciona clientes para **60+ microservicios** del ecosistema Fiado:
+
+### Servicios Core
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `IDirectoryApi` | Gestión de directorios de usuarios | `DIRECTORY_LAMBDA_URL` |
+| `IIdentityApi` | Verificación de identidad | `IDENTITY_LAMBDA_URL` |
+| `IAuthenticationApi` | Autenticación y tokens | `AUTHENTICATION_LAMBDA_URL` |
+| `ITransactionApi` | Procesamiento de transacciones | `TRANSACTION_LAMBDA_URL` |
+
+### Servicios de Cuenta
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `IAccountFiadoIncApi` | Cuentas Fiado Inc | `ACCOUNT_FIADOINC_LAMBDA_URL` |
+| `IAccountFiadoSAApi` | Cuentas Fiado SA | `ACCOUNT_FIADOSA_LAMBDA_URL` |
+| `IAccountPagoConfiadoApi` | Cuentas PagoConfiado | `ACCOUNT_PAGOCONFIADO_LAMBDA_URL` |
+| `IAccountBeneficiaryApi` | Beneficiarios de cuentas | `ACCOUNT_BENEFICIARY_LAMBDA_URL` |
+| `IBankAccountApi` | Cuentas bancarias | `BANK_ACCOUNT_LAMBDA_URL` |
+
+### Servicios de Pago
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `IStpSpeiApi` | Transferencias SPEI | `STP_SPEI_LAMBDA_URL` |
+| `IStpServicePaymentApi` | Pagos de servicios STP | `STP_SERVICE_PAYMENT_LAMBDA_URL` |
+| `ICentralPaymentsConnectorApi` | Conector de pagos central | `CENTRAL_PAYMENTS_LAMBDA_URL` |
+| `ICollectorApi` | Cobranza | `COLLECTOR_LAMBDA_URL` |
+
+### Servicios de Tarjeta
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `ICardApi` | Gestión de tarjetas | `CARD_LAMBDA_URL` |
+| `IPomeloApi` | Integración Pomelo | `POMELO_LAMBDA_URL` |
+| `IPomeloProcessorApi` | Procesador Pomelo | `POMELO_PROCESSOR_LAMBDA_URL` |
+
+### Servicios de Riesgo y Fraude
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `IRiskProfileApi` | Perfiles de riesgo | `RISK_PROFILE_LAMBDA_URL` |
+| `IFraudPreventionEngineApi` | Motor antifraude | `FRAUD_PREVENTION_LAMBDA_URL` |
+| `IBlackListApi` | Listas negras | `BLACKLIST_LAMBDA_URL` |
+| `ITransactionAlertApi` | Alertas de transacciones | `RISK_PROFILE_LAMBDA_URL` |
+
+### Servicios de Onboarding
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `IOnboardingApi` | Onboarding de usuarios | `ONBOARDING_LAMBDA_URL` |
+| `IOnboardingBusinessApi` | Onboarding de negocios | `ONBOARDING_BUSINESS_LAMBDA_URL` |
+| `ICnbvApi` | Integración CNBV | `CNBV_BUSINESS_LAMBDA_URL` |
+
+### Servicios de Comunicación
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `IFiadoMessagesApi` | Mensajería interna | `FIADO_MESSAGES_LAMBDA_URL` |
+| `IFirebaseConnectorApi` | Push notifications | `FIREBASE_CONNECTOR_LAMBDA_URL` |
+| `IZendeskApi` | Integración Zendesk | `ZENDESK_LAMBDA_URL` |
+
+### Servicios de Negocio
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `IActivityApi` | Actividades de negocio | `ACTIVITY_BUSINESS_LAMBDA_URL` |
+| `IServiceApi` | Servicios de negocio | `SERVICE_BUSINESS_LAMBDA_URL` |
+| `IPriceListApi` | Listas de precios | `PRICELIST_BUSINESS_LAMBDA_URL` |
+| `IPayrollApi` | Nómina | `PAYROLL_BUSINESS_LAMBDA_URL` |
+| `IOrderCollectorApi` | Órdenes de cobranza | `ORDER_COLLECTOR_LAMBDA_URL` |
+
+### Servicios Auxiliares
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `IAddressApi` | Direcciones | `ADDRESS_LAMBDA_URL` |
+| `IContactInformationApi` | Información de contacto | `CONTACT_INFORMATION_LAMBDA_URL` |
+| `IDeviceApi` | Dispositivos | `DEVICE_LAMBDA_URL` |
+| `IGroupApi` | Grupos | `GROUP_LAMBDA_URL` |
+| `IP2pContactApi` | Contactos P2P | `P2P_CONTACT_LAMBDA_URL` |
+| `IExchangeRatesApi` | Tipos de cambio | `EXCHANGE_RATES_LAMBDA_URL` |
+| `IProductCatalogApi` | Catálogo de productos | `PRODUCT_CATALOG_LAMBDA_URL` |
+| `IContractGeneratorApi` | Generador de contratos | `CONTRACT_GENERATOR_LAMBDA_URL` |
+| `IDocumentImageProcessorApi` | Procesador de imágenes | `DOCUMENT_IMAGE_PROCESSOR_LAMBDA_URL` |
+| `ILegalDocumentApi` | Documentos legales | `LEGAL_DOCUMENT_LAMBDA_URL` |
+| `IObservationsApi` | Observaciones | `OBSERVATIONS_LAMBDA_URL` |
+| `IDirectoriesApi` | Directorios múltiples | `DIRECTORIES_LAMBDA_URL` |
+| `IDirectorySettingApi` | Configuración de directorio | `DIRECTORY_SETTING_LAMBDA_URL` |
+| `IAppSelectionDataApi` | Datos de selección de app | `APP_SELECTION_DATA_LAMBDA_URL` |
+| `IReferralBusinessApi` | Referidos | `REFERRAL_BUSINESS_LAMBDA_URL` |
+| `IEventHistoryApi` | Historial de eventos | `EVENT_HISTORY_LAMBDA_URL` |
+| `IReportProcessorBusinessApi` | Procesador de reportes | `REPORT_PROCESSOR_LAMBDA_URL` |
+| `IPeopleBusinessApi` | Gestión de personas | `PEOPLE_BUSINESS_LAMBDA_URL` |
+
+### Integraciones Externas
+
+| Interface | Descripción | Variable de Entorno |
+|-----------|-------------|---------------------|
+| `ITernApi` | Integración Tern | `TERN_LAMBDA_URL` |
+| `IBBVARstApi` | Integración BBVA RST | `BBVA_RST_LAMBDA_URL` |
+| `IEstafetaApi` | Integración Estafeta | `ESTAFETA_LAMBDA_URL` |
+| `ICognitoConnectorApi` | Conector Cognito | `COGNITO_CONNECTOR_LAMBDA_URL` |
+| `ICognitoV2Api` | Cognito V2 | `COGNITO_CONNECTOR_LAMBDA_URL` |
+| `ISTPAccountApi` | Cuentas STP | `STP_ACCOUNT_LAMBDA_URL` |
+
+---
+
+## Publishers (Colas SQS)
+
+Para comunicación asíncrona, la librería provee publishers que envían mensajes a colas SQS:
+
+| Interface | Descripción | Variable de Entorno (Queue) |
+|-----------|-------------|----------------------------|
+| `INotificationMessagesPublisher` | Notificaciones push/email/sms | `NOTIFICATION_MESSAGES_QUEUE` |
+| `INotificationWSMessagesPublisher` | Notificaciones WebSocket | `NOTIFICATION_WS_QUEUE` |
+| `ISessionActivityPublisher` | Actividad de sesión | `SESSION_ACTIVITY_QUEUE` |
+| `ITransactionPublisher` | Eventos de transacción | `TRANSACTION_QUEUE` |
+| `IActivityPublisher` | Eventos de actividad | `ACTIVITY_QUEUE` |
+| `ITransactionAlarmPublisher` | Alarmas de transacción | `TRANSACTION_ALARM_QUEUE` |
+| `IPublisher` | Publisher genérico | Configurable |
+
+### Ejemplo de Publisher
+
+```typescript
+import { inject, injectable } from "inversify";
+import { INotificationMessagesPublisher } from "@fiado/api-invoker";
+import { NotificationQueueMessageRequest } from "@fiado/type-kit";
+
+@injectable()
+export class NotificationService {
+    constructor(
+        @inject("INotificationMessagesPublisher") 
+        private notificationPublisher: INotificationMessagesPublisher
+    ) {}
+
+    async sendPushNotification(userId: string, message: string): Promise<void> {
+        const notification: NotificationQueueMessageRequest = {
+            userId,
+            type: "PUSH",
+            message,
+            timestamp: new Date().toISOString()
+        };
+        
+        await this.notificationPublisher.publish(notification);
+    }
+}
+```
+
+---
+
+## Uso en Proyectos
+
+### Ejemplo: Consultar Directorio
+
+```typescript
+import { inject, injectable } from "inversify";
+import { IDirectoryApi } from "@fiado/api-invoker";
+import { log } from "@fiado/logger";
+
+@injectable()
+export class UserService {
+    constructor(
+        @inject("IDirectoryApi") private directoryApi: IDirectoryApi
+    ) {}
+
+    async getUsersByIds(directoryIds: string[]): Promise<any[]> {
+        try {
+            const response = await this.directoryApi.getByIds(directoryIds);
+            log.info("Directories fetched successfully", { count: response.length });
+            return response;
+        } catch (error) {
+            log.error("Error fetching directories", error);
+            throw error;
+        }
+    }
+
+    async getUserByPhone(phoneNumber: string): Promise<any> {
+        return await this.directoryApi.getByPhoneNumber(phoneNumber);
+    }
+}
+```
+
+### Ejemplo: Procesar Transacción
+
+```typescript
+import { inject, injectable } from "inversify";
+import { ITransactionApi, ITransactionPublisher } from "@fiado/api-invoker";
+
+@injectable()
+export class PaymentManager {
+    constructor(
+        @inject("ITransactionApi") private transactionApi: ITransactionApi,
+        @inject("ITransactionPublisher") private transactionPublisher: ITransactionPublisher
+    ) {}
+
+    async processPayment(paymentData: any): Promise<void> {
+        // 1. Crear transacción via API síncrona
+        const transaction = await this.transactionApi.create(paymentData);
+        
+        // 2. Publicar evento para procesamiento asíncrono
+        await this.transactionPublisher.publish({
+            transactionId: transaction.id,
+            event: "PAYMENT_INITIATED",
+            timestamp: new Date().toISOString()
+        });
+    }
+}
+```
+
+### Ejemplo: Verificación de Identidad
+
+```typescript
+import { inject, injectable } from "inversify";
+import { IIdentityApi, IRiskProfileApi } from "@fiado/api-invoker";
+
+@injectable()
+export class KYCService {
+    constructor(
+        @inject("IIdentityApi") private identityApi: IIdentityApi,
+        @inject("IRiskProfileApi") private riskProfileApi: IRiskProfileApi
+    ) {}
+
+    async verifyUser(directoryId: string, documents: any): Promise<boolean> {
+        // Verificar identidad
+        const identityResult = await this.identityApi.verify(directoryId, documents);
+        
+        // Evaluar perfil de riesgo
+        const riskProfile = await this.riskProfileApi.evaluate(directoryId);
+        
+        return identityResult.verified && riskProfile.score < 0.5;
+    }
+}
+```
+
+---
+
+## Variables de Entorno
+
+Cada cliente API requiere una variable de entorno con la URL base del Lambda destino. El formato estándar es:
+
+```
+{SERVICE_NAME}_LAMBDA_URL=https://{api-id}.execute-api.{region}.amazonaws.com/v1/
+```
+
+### Configuración en template.yml
+
+```yaml
+Environment:
+  Variables:
+    DIRECTORY_LAMBDA_URL: !Sub "{{resolve:ssm:fiado-directory-lambda}}"
+    IDENTITY_LAMBDA_URL: !Sub "{{resolve:ssm:fiado-identity-lambda}}"
+    TRANSACTION_LAMBDA_URL: !Sub "{{resolve:ssm:fiado-transaction-lambda}}"
+    # ... otras URLs
+    
+    # Colas SQS
+    NOTIFICATION_MESSAGES_QUEUE: !ImportValue SqsNotificationMessagesQueueUrl
+    SESSION_ACTIVITY_QUEUE: !ImportValue SqsSessionActivityQueueUrl
+```
+
+### Resolución de URLs
+
+Las URLs se almacenan en **SSM Parameter Store** y se resuelven en tiempo de despliegue. El pipeline de CI/CD registra automáticamente la URL de cada Lambda después del deploy.
+
+---
+
+## Estructura del Proyecto
+
+```
+src/
+├── index.ts                    # Exportaciones públicas
+├── container.config.ts         # ContainerModule con todos los bindings
+├── utils/                      # Utilidades compartidas
+│   └── InvokerUtils.ts
+│
+├── directory/                  # Ejemplo de estructura de módulo
+│   ├── index.ts               # Re-exportaciones del módulo
+│   ├── DirectoryApi.ts        # Implementación del cliente
+│   └── interfaces/
+│       └── IDirectoryApi.ts   # Interface del cliente
+│
+├── transaction/               # Módulo con API y Publisher
+│   ├── index.ts
+│   ├── api/
+│   │   ├── TransactionApi.ts
+│   │   └── ITransactionApi.ts
+│   └── queue/
+│       ├── TransactionPublisher.ts
+│       └── ITransactionPublisher.ts
+│
+├── notificationMessages/      # Módulo solo Publisher
+│   ├── index.ts
+│   └── queue/
+│       ├── NotificationMessagePublisher.ts
+│       └── interfaces/
+│           └── INotificationMessagesPublisher.ts
+│
+└── [60+ módulos adicionales...]
+```
+
+### Estructura de un Módulo API
+
+```
+{service-name}/
+├── index.ts                   # export * from './interfaces/I{Service}Api';
+│                              # export * from './{Service}Api';
+├── {Service}Api.ts            # Implementación @injectable()
+└── interfaces/
+    └── I{Service}Api.ts       # Interface con JSDoc
+```
+
+### Estructura de un Módulo con Queue
+
+```
+{service-name}/
+├── index.ts
+├── api/
+│   ├── {Service}Api.ts
+│   └── I{Service}Api.ts
+└── queue/
+    ├── {Service}Publisher.ts
+    └── interfaces/
+        └── I{Service}Publisher.ts
+```
+
+---
+
+## Convenciones de Desarrollo
+
+### Nomenclatura
+
+| Elemento | Patrón | Ejemplo |
+|----------|--------|---------|
+| **Carpeta de módulo** | `kebab-case` | `account-fiadoinc/` |
+| **Interface API** | `I{Service}Api` | `IDirectoryApi` |
+| **Implementación API** | `{Service}Api` | `DirectoryApi` |
+| **Interface Publisher** | `I{Service}Publisher` | `ITransactionPublisher` |
+| **Implementación Publisher** | `{Service}Publisher` | `TransactionPublisher` |
+
+### Patrón de Implementación API
+
+```typescript
+import dotenv from 'dotenv';
+import { inject, injectable } from "inversify";
+import { IHttpRequest } from "@fiado/http-client";
+import { I{Service}Api } from "./interfaces/I{Service}Api";
+dotenv.config();
+
+@injectable()
+export class {Service}Api implements I{Service}Api {
+    
+    private readonly baseUrl = process.env.{SERVICE}_LAMBDA_URL || "";
+
+    constructor(
+        @inject("IHttpRequest") private httpRequest: IHttpRequest
+    ) {}
+
+    public async getById(id: string): Promise<any> {
+        const url = `${this.baseUrl}?id=${id}`;
+        const operationName = "getById";
+        
+        return await this.httpRequest.get(url, null, { 
+            'operationName': operationName 
+        });
+    }
+}
+```
+
+### Patrón de Implementación Publisher
+
+```typescript
+import { SendMessageCommand, SQSClient } from "@aws-sdk/client-sqs";
+import { inject, injectable } from "inversify";
+import { I{Service}Publisher } from "./interfaces/I{Service}Publisher";
+
+@injectable()
+export class {Service}Publisher implements I{Service}Publisher {
+    
+    private readonly queueUrl = process.env.{SERVICE}_QUEUE;
+
+    async publish(message: any): Promise<void> {
+        const client = new SQSClient();
+        const command = new SendMessageCommand({
+            QueueUrl: this.queueUrl,
+            MessageBody: JSON.stringify(message)
+        });
+        await client.send(command);
+    }
+}
+```
+
+### Header operationName
+
+Todas las llamadas HTTP incluyen el header `operationName` que permite:
+- Trazabilidad en logs
+- Métricas por operación
+- Debugging en X-Ray
+
+---
+
+## Dependencias
+
+### Runtime
+
+| Dependencia | Versión | Propósito |
+|-------------|---------|-----------|
+| `@aws-sdk/client-sqs` | ^3.919.0 | Cliente SQS para publishers |
+| `@fiado/gateway-adapter` | ^1.1.50 | Tipos de respuesta API |
+| `@fiado/http-client` | ^1.0.7 | Cliente HTTP base |
+| `@fiado/logger` | ^1.0.3 | Logging estructurado |
+| `@fiado/type-kit` | ^2.1.28 | DTOs y tipos compartidos |
+| `inversify` | ^6.2.2 | Inyección de dependencias |
+| `reflect-metadata` | ^0.2.2 | Metadatos para decoradores |
+| `dotenv` | ^16.4.7 | Variables de entorno |
+
+### Desarrollo
+
+| Dependencia | Versión | Propósito |
+|-------------|---------|-----------|
+| `@types/node` | ^20.17.24 | Tipos de Node.js |
+| `typescript` | (peer) | Compilador TypeScript |
+
+---
+
+## Compilación y Publicación
+
+### Build
+
+```bash
+npm run build
+```
+
+Genera archivos `.js` y `.d.ts` en el directorio `bin/`.
+
+### Publicación
+
+```bash
+npm version patch|minor|major
+npm publish
+```
+
+La librería se publica en el registry npm privado de Fiado configurado en `.npmrc`.
+
+---
+
+<div align="center">
+
+**Fiado Inc.** | @fiado/api-invoker v1.5.34
+
+</div>
+
+