SDK de Midaz para TypeScript

Construye integraciones financieras tipadas con el SDK de Midaz para TypeScript — builder pattern, reintentos automáticos, observabilidad y validación estricta.

El SDK de Midaz para TypeScript te ayuda a construir integraciones financieras. Te da una interfaz tipada y amigable para desarrolladores sobre la plataforma de servicios financieros de Midaz. Te concentras en tu lógica de negocio, no en el código de transporte.

El SDK trabaja con Organizaciones, Ledgers, Cuentas, Transacciones y más. Úsalo para un flujo de trabajo simple o para operaciones complejas.

Una arquitectura modular en capas soporta el rendimiento, la extensibilidad y la experiencia del desarrollador.

​

¿Por qué usar el SDK de Midaz para TypeScript?

• Seguridad de tipos por diseño: Soporte completo de TypeScript con definiciones de tipos precisas.
• Patrón de constructor: Interfaces fluidas y legibles para construir objetos complejos.
• Manejo robusto de errores: Estrategias de recuperación y señales de error claras.
• Observabilidad incluida: Rastreo, métricas y registros, listos para usar.
• Arquitectura en capas: Separación limpia entre cliente, entidades, API y modelos.
• Reintentos automáticos: Políticas de reintento configurables para fallos transitorios.
• Controles de concurrencia: Herramientas integradas para ejecutar tareas en paralelo con control del rendimiento.
• Rápido con caché: Caché en memoria para mejor rendimiento.
• Validación estricta: Detecta entrada inválida temprano con mensajes de error claros.

​

Comenzando

---

​

Prerrequisito

• El SDK de Midaz para TypeScript requiere TypeScript v5.8 o posterior.

​

Instalación del SDK

Instala el SDK de Midaz para TypeScript con uno de los siguientes comandos:

npm

npm install @lerianstudio/midaz-sdk

Después de instalarlo, sigue la Guía de Inicio Rápido para aprender a usar el SDK.

​

Autenticación

---

El SDK de Midaz para TypeScript se autentica a través del Access Manager de Lerian (OAuth). Para un stack local con la autenticación deshabilitada, puedes construir un cliente sin él.

Nunca llamas a una función createClient — construye una configuración con createClientConfigWithAccessManager() (o createClientConfigBuilder() para un stack local sin autenticación) y pásala a new MidazClient(config).

​

Autenticación con Access Manager

Para integrar con proveedores de identidad externos mediante OAuth:

TypeScript

import { createClientConfigWithAccessManager, MidazClient } from '@lerianstudio/midaz-sdk';

const client = new MidazClient(
  createClientConfigWithAccessManager({
    address: 'https://auth.example.com',
    clientId: 'tu-client-id',
    clientSecret: 'tu-client-secret',
  }).withEnvironment('sandbox')
);

El Access Manager maneja los tokens por ti: adquisición, almacenamiento en caché y renovación. No gestionas tokens manualmente.

​

Desarrollo local (sin autenticación)

Para un stack local de Midaz con la autenticación deshabilitada, construye un cliente sin el Access Manager:

TypeScript

import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk';

const client = new MidazClient(
  createClientConfigBuilder().withEnvironment('development')
);

Ofrecemos un plugin de Access Manager que puedes usar. Si deseas saber más al respecto, contáctanos.

​

Guía de inicio rápido

---

Las siguientes secciones te dan ejemplos de código prácticos para el SDK de Midaz para TypeScript.

​

Crear un cliente

Este es el primer paso. El cliente es tu punto de entrada principal al SDK. Maneja la autenticación y te da acceso a todos los servicios de entidades.

Ejemplo:

TypeScript

import { createClientConfigBuilder, MidazClient } from '@lerianstudio/midaz-sdk';

const client = new MidazClient(
  createClientConfigBuilder().withEnvironment('sandbox') // Options: 'development', 'sandbox', 'production'
);

​

Crear un Activo

Crea activos con el patrón de constructor y createAssetBuilder.

Ejemplo:

TypeScript

import { createAssetBuilder } from '@lerianstudio/midaz-sdk';

const assetInput = createAssetBuilder('US Dollar', 'USD')
  .withType('currency')
  .withMetadata({ precision: 2, symbol: '$' })
  .build();

const asset = await client.entities.assets.createAsset('org_123', 'ledger_456', assetInput);

En este código, agregas los campos obligatorios name y assetCode al constructor const assetInput = createAssetBuilder('US Dollar', 'USD'). Luego agregas cualquier otra propiedad con los métodos with*.

​

Crear una Cuenta

Crea cuentas con el patrón de constructor y createAccountBuilder.

Ejemplo:

TypeScript

import { createAccountBuilder } from '@lerianstudio/midaz-sdk';

const accountInput = createAccountBuilder('Savings Account', 'USD')
  .withType('savings')
  .withAlias('personal-savings')
  .build();

const account = await client.entities.accounts.createAccount('org_123', 'ledger_456', accountInput);

En este código, agregas los campos obligatorios name y assetCode al constructor const accountInput = createAccountBuilder('Savings Account', 'USD'). Luego agregas cualquier otra propiedad con los métodos with*.

​

Crear una Transacción

Crea transacciones con el patrón de constructor y createTransactionBuilder.

Ejemplo:

TypeScript

import { createTransactionBuilder } from '@lerianstudio/midaz-sdk';

const transactionInput = createTransactionBuilder()
  .withCode('payment_001')
  .withOperations([
    {
      accountId: 'source_account_id',
      assetCode: 'USD',
      amount: 100 * 100, // $100.00
      type: 'debit',
    },
    {
      accountId: 'destination_account_id',
      assetCode: 'USD',
      amount: 100 * 100, // $100.00
      type: 'credit',
    },
  ])
  .withMetadata({ purpose: 'Pago mensual' })
  .build();

En este código, agregas todas las propiedades con los métodos with*.

​

Recuperación de errores

Usa la recuperación de errores mejorada para operaciones críticas.

TypeScript

import { withEnhancedRecovery } from '@lerianstudio/midaz-sdk/util/error';

const result = await withEnhancedRecovery(
  () => client.entities.transactions.createTransaction('org_123', 'ledger_456', transactionInput),
  {
    maxRetries: 3,
    enableSmartRecovery: true,
  }
);

​

Limpiar recursos

TypeScript

client.close();

​

Usar Access Manager para autenticación

TypeScript

import { createClientConfigWithAccessManager, MidazClient } from '@lerianstudio/midaz-sdk';

// Inicializa el cliente con autenticación de Access Manager
const client = new MidazClient(
  createClientConfigWithAccessManager({
    address: 'https://auth.example.com', // Dirección del proveedor de identidad
    clientId: 'your-client-id', // ID del cliente OAuth
    clientSecret: 'your-client-secret', // Secreto del cliente OAuth
    tokenEndpoint: '/oauth/token', // Opcional, por defecto '/oauth/token'
    refreshThresholdSeconds: 300, // Opcional, por defecto 300 (5 minutos)
  })
    .withEnvironment('sandbox')
    .withApiVersion('v1')
);

// El SDK gestionará automáticamente la obtención y renovación del token
// Ahora puedes usar el cliente con normalidad
const organizations = await client.entities.organizations.listOrganizations();

// Para configuraciones específicas por entorno con Access Manager
const sandboxClient = new MidazClient(
  createSandboxConfigWithAccessManager({
    address: 'https://auth.example.com',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  })
);

// Libera los recursos cuando termines
client.close();

​

Arquitectura del SDK

---

El SDK de Midaz usa una arquitectura de servicios de múltiples capas para una experiencia de desarrollador limpia, modular y escalable. Tiene tres capas, mostradas en la Figura 1. Cada capa sirve un propósito distinto.

• Interfaz del cliente: Este es el punto de entrada principal para los usuarios del SDK. Gestiona la configuración como claves API y entornos. Inicializa servicios de manera perezosa y expone toda la funcionalidad del SDK.
• Capa de servicios de entidades: Esta capa contiene servicios específicos de dominio, como Cuentas, Activos y Transacciones. Cada servicio ofrece métodos consistentes: crear, obtener, actualizar, eliminar y listar. Cada servicio también agrega operaciones especializadas para su entidad.
• Capa de servicios centrales: Todos los servicios de entidades usan estas utilidades fundamentales. Manejan solicitudes HTTP, validación de entrada, procesamiento de errores, observabilidad, configuración y almacenamiento en caché.

Figura 1. La arquitectura en capas del SDK de Midaz para TypeScript.

La arquitectura del SDK enfatiza:

• Consistencia a través de patrones compartidos en todos los servicios.
• Escalabilidad mediante inyección de dependencias y fábricas de servicios.
• Confiabilidad a través de manejo mejorado de errores y respuestas tipadas.
• Facilidad de prueba con soporte para pruebas de simulación, integración y contrato.

¿Quieres profundizar más? Consulta las siguientes páginas para más información sobre la Arquitectura:

• Resumen de la arquitectura del SDK de Midaz.
• Arquitectura de la interfaz del cliente.
• Arquitectura de la capa de servicio.

​

Patrón de constructor

---

El SDK de Midaz para TypeScript usa un patrón de constructor para ayudarte a ensamblar objetos complejos de manera segura y adaptable. En lugar de un conjunto fijo de entradas, te da una interfaz fluida, paso a paso y encadenable.

Funciones de constructor en el SDK:

• Te informan los parámetros por adelantado.
• Te permiten definir campos opcionales con los métodos .with*() y encadenarlos.
• Evitan estados inválidos a través de una estructura guiada.
• Ocultan la complejidad interna para mejor legibilidad.

​

Ejemplo

Aquí hay un ejemplo rápido:

TypeScript

const assetInput = createAssetBuilder('USD Currency', 'USD')
  .withType('currency')
  .withMetadata({ precision: 2 })
  .build();

Luego puedes pasar este assetInput al método de creación correspondiente en el SDK.

¿Quieres profundizar más? Consulta la página Patrón de Constructor en el SDK de Midaz para más información.

​

Trabajando con entidades

---

Cada servicio de entidad cubre una parte distinta del dominio financiero, como cuentas, activos o transacciones.

Estos servicios crean, recuperan, actualizan y eliminan datos para cada tipo de entidad.

También ofrecen características especializadas para cada caso de uso, para que manejes datos financieros con confianza.

Entidad	Descripción
Organizaciones	Gestionar unidades de negocio y datos organizacionales.
Ledgers	Estructurar y gestionar registros financieros.
Activos	Trabajar con activos como monedas, commodities y otras unidades de valor.
Cuentas	Crear, recuperar, actualizar y eliminar cuentas dentro de un Libro Contable.
Segmentos	Organizar portafolios para análisis e informes.
Portafolios	Agrupar cuentas y activos en colecciones financieras significativas.
Saldos	Recuperar y calcular saldos de activos para cuentas.
Tasas de Activos	Manejar tasas de cambio entre diferentes tipos de activos.
Transacciones	Crear y gestionar transacciones que mueven activos entre cuentas.
Operaciones	Gestionar débitos y créditos atómicos que conforman una transacción.

Accedes a cada servicio a través del cliente SDK. Siguen una estructura consistente, para que construyas y mantengas características financieras más fácilmente.

¿Quieres profundizar más? Consulta las páginas de Entidades para más información.

​

Uso de utilidades

---

El SDK proporciona módulos de utilidad para operaciones comunes: rendimiento, manejo de errores, configuración y observabilidad.

Estas herramientas trabajan con el resto del SDK y te ayudan a construir aplicaciones financieras con menos esfuerzo.

Utilidad	Descripción
Ayudantes de Cuenta	Simplifica la lógica y transformaciones comunes relacionadas con cuentas.
Caché	Habilita almacenamiento en caché ligero para un mejor rendimiento en tiempo de ejecución.
Concurrencia	Ayuda a coordinar y limitar tareas concurrentes de manera segura y eficiente.
Configuración	Configuración y acceso centralizados.
Datos	Asiste con formateo de datos y tareas de paginación.
Manejo de Errores	Ofrece estrategias de recuperación y mecanismos de procesamiento de errores.
Cliente HTTP	Proporciona una interfaz HTTP de bajo nivel para llamadas API directas.
Red	Agrega características de red de alto nivel como reintentos y retroceso.
Observabilidad	Captura trazas, métricas y registros para soportar monitoreo y depuración.
Paginación	Maneja respuestas paginadas con ayudantes predecibles y consistentes.
Validación	Valida datos de entrada y salida para ayudar a mantener la integridad de datos.

¿Quieres profundizar más? Consulta las páginas de Utilidades para más información.

​

Manejo de errores

---

El SDK de Midaz para TypeScript te ayuda a manejar errores de manera clara y consistente. Cuando ocurre un error durante una operación del SDK, el SDK lanza un error estructurado. El error incluye campos clave:

• code: Un identificador corto y consistente para el tipo de error.
• message: Una descripción legible por humanos.
• statusCode: El código de estado HTTP, cuando esté disponible.

Maneja un error así:

TypeScript

try {
  await client.transactions.create(transaction);
} catch (err) {
  console.error(`Error (${err.code}): ${err.message}`);
  // Opcionalmente: inspecciona err.statusCode
}

​

Códigos de error comunes

Código	Descripción	Estado HTTP
invalid_input	Tu solicitud falta datos requeridos o tiene valores inválidos.	400
unauthorized	La autenticación falló o faltan credenciales.	401
forbidden	No tienes permiso para realizar esta acción.	403
not_found	El recurso al que intentas acceder no existe.	404
conflict	La operación entra en conflicto con un recurso existente.	409
internal_error	Algo salió mal de nuestro lado.	500
service_unavailable	Interrupción temporal—intenta de nuevo más tarde.	503

​

Mejores prácticas

• Valida la entrada antes de llamar a los métodos del SDK, para evitar invalid_input.
• Verifica tu autenticación cuando obtengas unauthorized o forbidden.
• Reintenta en problemas transitorios como internal_error o service_unavailable.
• Usa statusCode y message para mostrar información de depuración en los registros de desarrollo.

El SDK mantiene los errores predecibles y accionables.

Consejo

¿Quieres profundizar más? Consulta las siguientes páginas para más información:

• Manejo de errores en el SDK de Midaz.
• Arquitectura de manejo de errores.
• Manejo de errores (Utilidades).

​

Pipeline de CI/CD

---

Usamos GitHub Actions para builds automatizados y listos para producción:

• Ejecuta pruebas en múltiples versiones de Node.js.
• Hace cumplir la calidad del código con ESLint y Prettier.
• Mantiene las dependencias actualizadas con Dependabot.
• Maneja versiones automáticamente con versionado semántico.
• Genera registros de cambios.

​

¿Quieres contribuir?

---

Para contribuir al SDK de Midaz para TypeScript, comienza con nuestra guía de contribución en GitHub. Cubre lo que necesitas para comenzar.

​

Licencia

---

Este proyecto está licenciado bajo la Apache License 2.0. Para más detalles, consulta la página de Licencia.