SDK de Midaz para TypeScript

​

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

• Tipado seguro por diseño: compatibilidad total con TypeScript y definiciones de tipos precisas.
• Patrón builder: interfaces fluidas y legibles para construir objetos complejos.
• Manejo de errores: estrategias de recuperación y señales de error claras.
• Observabilidad incluida: trazas, métricas y logs listos para usar.
• Arquitectura por capas: separación clara entre el cliente, las entidades, la API y los modelos.
• Reintentos automáticos: políticas de reintento configurables para fallas transitorias.
• Controles de concurrencia: herramientas integradas para ejecutar tareas en paralelo con un rendimiento controlado.
• Rápido gracias al cache: cache en memoria para un mejor rendimiento.
• Validación estricta: detecta datos de entrada inválidos desde el principio, con mensajes de error claros.

​

Primeros pasos

​

Prerrequisito

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

​

Instalar el SDK

npm install @lerianstudio/midaz-sdk

yarn add @lerianstudio/midaz-sdk

​

Autenticación

​

Autenticación con Access Manager

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

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

​

Desarrollo local (sin autenticación)

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

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

​

Guía de inicio rápido

​

Crear un cliente

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

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

​

Crear un Activo

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);

​

Crear una Cuenta

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);

​

Crear una Transacción

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: 'Monthly payment' })
  .build();

​

Recuperación de errores

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,
  }
);

​

Liberar recursos

client.close();

​

Usar Access Manager para la autenticación

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

// Initialize the client with Access Manager authentication
const client = new MidazClient(
  createClientConfigWithAccessManager({
    address: 'https://auth.example.com', // Identity provider address
    clientId: 'your-client-id', // OAuth client ID
    clientSecret: 'your-client-secret', // OAuth client secret
    tokenEndpoint: '/oauth/token', // Optional, defaults to '/oauth/token'
    refreshThresholdSeconds: 300, // Optional, defaults to 300 (5 minutes)
  })
    .withEnvironment('sandbox')
    .withApiVersion('v1')
);

// The SDK will automatically handle token acquisition and renewal
// You can now use the client as normal
const organizations = await client.entities.organizations.listOrganizations();

// For environment-specific configurations with Access Manager
const sandboxClient = new MidazClient(
  createSandboxConfigWithAccessManager({
    address: 'https://auth.example.com',
    clientId: 'your-client-id',
    clientSecret: 'your-client-secret',
  })
);

// Clean up resources when done
client.close();

​

Arquitectura del SDK

• Interfaz de cliente: es el punto de entrada principal para los usuarios del SDK. Gestiona la configuración, como las claves de API y los entornos. Inicializa los servicios de forma diferida y expone toda la funcionalidad del SDK.
• Capa de servicios de entidades: esta capa contiene los servicios específicos del 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 core: todos los servicios de entidades usan estas utilidades fundamentales. Gestionan las solicitudes HTTP, la validación de entradas, el procesamiento de errores, la observabilidad, la configuración y el cache.

• Consistencia mediante patrones compartidos entre los servicios.
• Escalabilidad a través de la inyección de dependencias y las fábricas de servicios.
• Confiabilidad mediante un manejo de errores mejorado y respuestas tipadas.
• Capacidad de prueba: admite mocking, pruebas de integración y pruebas de contrato.

​

Patrón builder

• Te indican los parámetros de antemano.
• Te permiten configurar campos opcionales con los métodos .with*() y encadenarlos.
• Evitan estados inválidos mediante una estructura guiada.
• Ocultan la complejidad interna para una mejor legibilidad.

​

Ejemplo

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

​

Trabajar con entidades

​

Usar utilidades

​

Manejo de errores

• code: un identificador breve y consistente para el tipo de error.
• message: una descripción legible para las personas.
• statusCode: el código de estado HTTP, cuando está disponible.

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

​

Códigos de error comunes

​

Mejores prácticas

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

​

Pipeline de CI/CD

• Ejecuta pruebas en varias versiones de Node.js.
• Aplica estándares de calidad de código con ESLint y Prettier.
• Mantiene las dependencias actualizadas con Dependabot.
• Gestiona los lanzamientos automáticamente con versionado semántico.
• Genera registros de cambios.

​

¿Quieres contribuir?

​

Licencia