Tabla de Contenidos

• Descripción General
• Arquitectura
• Instalación
• Configuración
• APIs Disponibles
• Publishers (Colas SQS)
• Uso en Proyectos
• Variables de Entorno
• Estructura del Proyecto
• Convenciones de Desarrollo
• 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

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

Servicios de Cuenta

Servicios de Pago

Servicios de Tarjeta

Servicios de Riesgo y Fraude

Servicios de Onboarding

Servicios de Comunicación

Servicios de Negocio

Servicios Auxiliares

Integraciones Externas

Publishers (Colas SQS)

Para comunicación asíncrona, la librería provee publishers que envían mensajes a colas SQS:

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

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

Desarrollo

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.