@fiado/api-invoker

v4.1.0

Published

4 hours ago

Sirve como un puente entre diferentes funciones lambda, facilitando la comunicación entre ellas a través de invocaciones http

Downloads

957

0High
0Medium
0Low

fiado

🔗 Fiado API Invoker

Librería de Comunicación Inter-Servicios para Microservicios Lambda

Tabla de Contenidos

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:

La construcción de URLs base desde variables de entorno
El manejo de headers y operaciones HTTP
La serialización/deserialización de payloads
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

npm install @fiado/api-invoker @fiado/http-client

Peer Dependencies

La librería requiere las siguientes dependencias en el proyecto consumidor:

{
  "@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:

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

// 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

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

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

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

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

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

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

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

npm run build

Genera archivos .js y .d.ts en el directorio bin/.

Publicación

npm version patch|minor|major
npm publish

La librería se publica en el registry npm privado de Fiado configurado en .npmrc.

Fiado Inc. | @fiado/api-invoker v1.5.34