@fiado/type-kit

Fiado Type Kit

Biblioteca de DTOs, Enums y Tipos Compartidos para el Ecosistema Fiado

Tabla de Contenidos

• Descripcion General
• Arquitectura
• Instalacion
• Dominios Disponibles
• Uso
• Convenciones de Desarrollo
• Estructura de Modulos
• Tipos Especiales
• Dependencias

Descripcion General

@fiado/type-kit es la biblioteca central de tipos del ecosistema Fiado que proporciona:

• DTOs (Data Transfer Objects): Clases tipadas para requests y responses de APIs
• Enums: Enumeraciones para estados, tipos y categorias del negocio
• Entities: Entidades base para modelos de datos
• Interfaces: Contratos compartidos entre microservicios
• Validaciones: Decoradores de class-validator para validacion de entrada

Proposito

En una arquitectura de microservicios, es fundamental mantener consistencia en los tipos de datos que se intercambian entre servicios. Esta biblioteca:

• Centraliza todas las definiciones de tipos en un solo lugar
• Garantiza que todos los microservicios usen las mismas estructuras
• Facilita la validacion de datos de entrada con decoradores
• Reduce duplicacion de codigo entre proyectos

Arquitectura

                    +------------------+
                    |  @fiado/type-kit |
                    +--------+---------+
                             |
        +--------------------+--------------------+
        |                    |                    |
        v                    v                    v
+---------------+    +---------------+    +---------------+
| Lambda Card   |    | Lambda Account|    | Lambda Trans  |
| Microservice  |    | Microservice  |    | Microservice  |
+---------------+    +---------------+    +---------------+
        |                    |                    |
        +--------------------+--------------------+
                             |
                             v
                    +------------------+
                    |   API Gateway    |
                    +------------------+

Flujo de Tipos

• Request: Cliente envia datos -> API Gateway -> Lambda valida con DTOs de Request
• Procesamiento: Lambda usa Enums y Entities para logica de negocio
• Response: Lambda retorna datos usando DTOs de Response -> Cliente

Instalacion

npm install @fiado/type-kit

Peer Dependencies

Esta biblioteca no tiene peer dependencies, pero utiliza internamente:

{
  "class-transformer": "^0.5.1",
  "class-validator": "^0.14.2"
}

Dominios Disponibles

La biblioteca esta organizada en 60+ dominios que cubren todas las areas del negocio:

Servicios Core

Dominio	Descripcion	Contenido
account	Cuentas bancarias y operaciones	44 DTOs, 12 Enums
card	Tarjetas fisicas y virtuales	40 DTOs, 26 Enums
transaction	Transacciones y movimientos	24 DTOs, 6 Enums
directory	Directorios de usuarios	8 DTOs, 6 Enums
identity	Verificacion de identidad (KYC)	7 DTOs, 8 Enums
authentication	Autenticacion y sesiones	10 DTOs

Servicios de Pago

Dominio	Descripcion	Contenido
transactionProcessor	Procesamiento de transacciones	39 DTOs, 7 Enums
centralPayments	Pagos centralizados	14 DTOs/Enums
stpSpei	Transferencias SPEI	10 DTOs/Enums
servicePayment	Pago de servicios	4 DTOs/Enums
collector	Cobranza	14 DTOs/Enums

Servicios de Usuario

Dominio	Descripcion	Contenido
beneficiary	Beneficiarios de transferencias	5 DTOs/Enums
bankAccount	Cuentas bancarias externas	10 DTOs/Enums
address	Direcciones	24 DTOs/Enums
contactInfo	Informacion de contacto	9 DTOs/Enums
group	Grupos de usuarios	11 DTOs/Enums
role	Roles y permisos	9 DTOs/Enums

Servicios de Riesgo

Dominio	Descripcion	Contenido
riskProfile	Perfiles de riesgo	13 DTOs, 10 Enums
fraudPreventionEngine	Prevencion de fraude	5 DTOs/Enums
blacklist	Listas negras	5 DTOs/Enums

Servicios de Negocio

Dominio	Descripcion	Contenido
issuanceBusiness	Emision de tarjetas	6 DTOs/Enums
pricelist	Listas de precios	9 DTOs/Enums
services	Catalogo de servicios	18 DTOs/Enums
productCatalog	Catalogo de productos	7 DTOs/Enums
contract	Contratos	3 DTOs/Enums
creditContract	Contratos de credito	3 DTOs/Enums

Servicios de Comunicacion

Dominio	Descripcion	Contenido
notificationMessages	Mensajes y notificaciones	4 DTOs, 2 Enums
notificationWS	WebSocket notifications	2 DTOs/Enums
helpdesk	Soporte al cliente	3 DTOs/Enums

Servicios de Infraestructura

Dominio	Descripcion	Contenido
header	Token payload de JWT	TokenPayload
eventBridge	Mensajes de EventBridge	EventBridgeMessageRequest
genericMessage	Mensajes genericos	GenericMessageSourceEnum
apiResponse	Respuesta estandar de API	FiadoApiResponse
queue	Tipos de colas	1 DTO

Otros Dominios

Dominio	Descripcion
activity	Actividades de usuario
app	Configuracion de aplicacion
auth	Autorizacion
bbvaRst	Integracion BBVA
cnbv	Reportes CNBV
cognitoConnector	Integracion Cognito
country	Paises y regiones
currency	Monedas
device	Dispositivos
exchangeRate	Tipos de cambio
observations	Observaciones KYC
p2pContact	Contactos P2P
provider	Proveedores
sessionActivity	Actividad de sesion
stpAccount	Cuentas STP

Uso

Importacion por Dominio (Recomendado)

// Importar desde el dominio especifico
import { 
    AccountCreateRequest, 
    AccountCreateResponse,
    AccountLevelEnum,
    BankAccountTypeEnum 
} from "@fiado/type-kit/bin/account";

import { 
    CardActivateRequest,
    CardResponse,
    CardType,
    CardIssuanceStatus 
} from "@fiado/type-kit/bin/card";

import { 
    TransactionCreateRequest,
    TransactionStatusEnum,
    OperationEnum 
} from "@fiado/type-kit/bin/transaction";

Importacion con Namespace

import { Account, Card, Transaction } from "@fiado/type-kit";

// Usar con namespace
const request: Account.AccountCreateRequest = { ... };
const cardType: Card.CardType = Card.CardType.VIRTUAL;
const status: Transaction.TransactionStatusEnum = Transaction.TransactionStatusEnum.COMPLETED;

Ejemplo: Crear una Cuenta

import { 
    AccountCreateRequest, 
    AccountCreateResponse,
    BankAccountTypeEnum,
    AccountLevelEnum 
} from "@fiado/type-kit/bin/account";

async function createAccount(data: AccountCreateRequest): Promise<AccountCreateResponse> {
    // Validar que el tipo de cuenta sea valido
    if (data.accountType === BankAccountTypeEnum.SAVINGS) {
        // Logica para cuenta de ahorro
    }
    
    // Verificar nivel de cuenta
    if (data.level === AccountLevelEnum.LEVEL_2) {
        // Requiere verificacion adicional
    }
    
    return { accountId: "...", status: "CREATED" };
}

Ejemplo: Procesar Transaccion

import { 
    TransactionCreateRequest,
    TransactionCreateResponse,
    TransactionStatusEnum,
    OperationEnum 
} from "@fiado/type-kit/bin/transaction";

async function processTransaction(
    request: TransactionCreateRequest
): Promise<TransactionCreateResponse> {
    
    if (request.operation === OperationEnum.CREDIT) {
        // Procesar credito
    } else if (request.operation === OperationEnum.DEBIT) {
        // Procesar debito
    }
    
    return {
        transactionId: "...",
        status: TransactionStatusEnum.COMPLETED
    };
}

Ejemplo: Validar Request con class-validator

import { validate } from 'class-validator';
import { plainToClass } from 'class-transformer';
import { CardActivateRequest } from "@fiado/type-kit/bin/card";

async function validateRequest(body: any): Promise<CardActivateRequest> {
    const request = plainToClass(CardActivateRequest, body);
    const errors = await validate(request);
    
    if (errors.length > 0) {
        throw new Error(`Validation failed: ${errors.map(e => e.toString()).join(', ')}`);
    }
    
    return request;
}

Convenciones de Desarrollo

Nomenclatura de DTOs

Tipo	Patron	Ejemplo
Request	{Entity}{Action}Request	CardActivateRequest, AccountCreateRequest
Response	{Entity}{Action}Response	CardBalanceResponse, AccountCreateResponse
Query	{Entity}QueryParams	TransactionQueryParams
Item	{Entity}Item	TransactionItem, PocketItem

Nomenclatura de Enums

Tipo	Patron	Ejemplo
Status	{Entity}StatusEnum	CardIssuanceStatus, TransactionStatusEnum
Type	{Entity}TypeEnum	BankAccountTypeEnum, CardType
Operation	{Action}Enum	OperationEnum, PocketOperationTypeEnum

Validaciones con class-validator

Requests: DEBEN incluir decoradores de validacion

import { IsNotEmpty, IsString, IsNumber, IsEnum, IsOptional } from 'class-validator';

export class CardActivateRequest {
    @IsNotEmpty()
    @IsString()
    readonly cardId: string;

    @IsNotEmpty()
    @IsString()
    readonly userId: string;

    @IsOptional()
    @IsEnum(ActivationMethod)
    readonly method?: ActivationMethod;
}

Responses: NO deben incluir validaciones

export class CardActivateResponse {
    cardId: string;
    status: CardIssuanceStatus;
    activatedAt: string;
}

Estructura de Modulo

Cada dominio sigue esta estructura:

{domain}/
├── dtos/                    # Data Transfer Objects
│   ├── {Entity}Request.ts
│   ├── {Entity}Response.ts
│   └── Internal/            # DTOs internos (opcional)
├── enums/                   # Enumeraciones
│   ├── {Entity}StatusEnum.ts
│   └── {Entity}TypeEnum.ts
├── entities/                # Entidades base (opcional)
│   └── {Entity}EntityBase.ts
├── constants/               # Constantes (opcional)
│   └── {entity}Constants.ts
└── index.ts                 # Exportaciones del modulo

Estructura de Modulos

Ejemplo: Modulo Account

account/
├── dtos/
│   ├── AccountCreateRequest.ts
│   ├── AccountCreateResponse.ts
│   ├── AccountUpdateRequest.ts
│   ├── GetAccountResponse.ts
│   ├── GetAccountBalanceResponse.ts
│   ├── BankAccountP2pTransferRequest.ts
│   ├── BankAccountP2pTransferResponse.ts
│   ├── SPEITransferCreateRequest.ts
│   ├── SPEITransferResponse.ts
│   └── ... (44 DTOs total)
├── entities/
│   ├── AccountEntityBase.ts
│   └── BankInfo.ts
├── enums/
│   ├── AccountEntityStatusEnum.ts
│   ├── BankAccountTypeEnum.ts
│   ├── AccountLevelEnum.ts
│   ├── SpeiTransferStatusEnum.ts
│   └── ... (12 Enums total)
└── index.ts

Ejemplo: Modulo Card

card/
├── dtos/
│   ├── CardActivateRequest.ts
│   ├── CardApplicationRequest.ts
│   ├── CardUpdateRequest.ts
│   ├── CardResponse.ts
│   ├── CardBalanceResponse.ts
│   ├── CardSensitiveInformationResponse.ts
│   └── Internal/
│       ├── CreateBankAccountCardRequest.ts
│       ├── CreateBankAccountCardResponse.ts
│       ├── ActivateBankAccountCardRequest.ts
│       └── ... (DTOs internos)
├── enums/
│   ├── CardType.ts
│   ├── CardIssuanceStatus.ts
│   ├── Brand.ts
│   ├── VirtualOrPhysical.ts
│   ├── ShippingStatus.ts
│   └── issuance/
│       ├── KycStatus.ts
│       ├── UserStatus.ts
│       └── IssuanceFlow.ts
├── validations/
│   └── cardValidations.ts
└── index.ts

Tipos Especiales

TokenPayload

Interface para el payload del token JWT de Cognito:

import { TokenPayload } from "@fiado/type-kit/bin/header";

interface TokenPayload {
    directoryId: string;           // ID del directorio
    typeOfDirectoryId: TypeOfDirectoryId;
    peopleId: string | null;       // ID de persona
    sub: string;                   // Subject (Cognito user ID)
    app: string;                   // Aplicacion origen
    issuer: string;                // Emisor del token
    scope: string;                 // Scope del token
    phoneNumber?: string | null;   // Telefono
    status: Status | null;         // Estado del usuario
    id: string;                    // ID interno
    profileId?: string | null;     // ID de perfil
    email?: string | null;         // Email
    event_id?: string;             // ID de evento
    sponsorDirectoryId?: string | null; // Sponsor
}

FiadoApiResponse

Interface estandar para respuestas de API:

import FiadoApiResponse from "@fiado/type-kit/bin/apiResponse";

interface FiadoApiResponse<T> {
    data: T;                    // Datos de respuesta
    date: string | null;        // Timestamp
    code: string | null;        // Codigo de respuesta
    msg: string | null;         // Mensaje
    description: string | null; // Descripcion
}

EventBridgeMessageRequest

Clase para mensajes de EventBridge:

import { EventBridgeMessageRequest } from "@fiado/type-kit/bin/eventBridge";

class EventBridgeMessageRequest<T> extends GenericMessageRequest<T> {
    // Hereda propiedades de GenericMessageRequest
    // - source: GenericMessageSourceEnum
    // - payload: T
    // - eventType: string
}

Dependencias

Runtime

Dependencia	Version	Proposito
class-transformer	^0.5.1	Transformacion de objetos planos a clases
class-validator	^0.14.2	Validacion de DTOs con decoradores

Desarrollo

Dependencia	Version	Proposito
@types/node	^20.11.20	Tipos de Node.js
typescript	^5.3.3	Compilador TypeScript

Compilacion y Publicacion

Build

npm run build

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

Test

npm test

Publicacion

npm version patch|minor|major
npm publish

Estructura del Proyecto

fiado-type-kit/
├── src/                        # Codigo fuente
│   ├── index.ts                # Exportaciones principales
│   ├── account/                # Dominio Account (59 items)
│   ├── card/                   # Dominio Card (69 items)
│   ├── transaction/            # Dominio Transaction (31 items)
│   ├── transactionProcessor/   # Dominio TransactionProcessor (47 items)
│   ├── directory/              # Dominio Directory (15 items)
│   ├── identity/               # Dominio Identity (16 items)
│   ├── riskProfile/            # Dominio RiskProfile (24 items)
│   ├── ... (60+ dominios)
│   └── header/                 # TokenPayload
├── bin/                        # Archivos compilados
├── package.json
├── tsconfig.json
└── README.md

Fiado Inc. | @fiado/type-kit v2.1.40