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

1. Request: Cliente envia datos -> API Gateway -> Lambda valida con DTOs de Request
2. Procesamiento: Lambda usa Enums y Entities para logica de negocio
3. 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