SDK de Midaz para TypeScript

​

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

• Seguridad de tipos por diseño: Construido con soporte completo de TypeScript y definiciones de tipos precisas.
• Patrón de constructor: Interfaces fluidas y legibles para ayudarle a construir objetos complejos con facilidad.
• Manejo robusto de errores: Estrategias inteligentes de recuperación y señales de error claras, para que mantenga el control.
• Observabilidad incluida: Rastreo, métricas y registros, listos desde el primer momento.
• Arquitectura en capas: Separación limpia entre cliente, entidades, API y modelos. Organizado, predecible, escalable.
• Reintentos automáticos: Maneje contratiempos transitorios con políticas de reintento configurables.
• Controles de concurrencia: Herramientas integradas para ejecutar tareas en paralelo, sin perder el control del rendimiento.
• Rápido con caché: Caché en memoria para aumentar el rendimiento donde cuenta.
• Validación estricta: Detecte entrada inválida temprano con mensajes de error claros y accionables.

​

Comenzando

​

Prerrequisito

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

​

Instalación del SDK

npm install midaz-sdk

​

Autenticación

​

Clave API

const client = createClient({
  apiKey: 'your-api-key',
  environment: 'sandbox',
});

​

Autenticación con Access Manager

const client = createClient({
  accessManager: {
    enabled: true,
    address: 'https://auth.example.com',
    clientId: 'tu-client-id',
    clientSecret: 'tu-client-secret',
  },
  environment: 'sandbox',
});

​

Guía de inicio rápido

​

Crear un cliente

import { createClient } from 'midaz-sdk';

const client = createClient({
  apiKey: 'tu-api-key',
  environment: 'sandbox', // Options: 'development', 'sandbox', 'production'
});

​

Crear un Activo

import { createAssetBuilder } from '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 '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 '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();

​

Recuperación de errores

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

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

​

Limpiar recursos

client.close();

​

Usar Access Manager para autenticación

import { createClientConfigWithAccessManager, MidazClient } from '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

• Interfaz del cliente: Este es el punto de entrada principal para los usuarios del SDK. Gestiona configuraciones como claves API y entornos, inicializa servicios de manera perezosa y expone toda la funcionalidad disponible de manera unificada y descubrible.
• Capa de servicios de entidades: Esta capa contiene servicios específicos de dominio (por ejemplo, Cuentas, Activos y Transacciones) y ofrece métodos consistentes para operaciones como crear, obtener, actualizar, eliminar y listar. Además, se incluyen operaciones especializadas basadas en las necesidades específicas de cada entidad.
• Capa de servicios centrales: Estas utilidades fundamentales son utilizadas por todos los servicios de entidades. 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.

• 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.

​

Patrón de constructor

• Lo asisten informándole de los parámetros por adelantado.
• Le permiten modificar campos opcionales usando métodos .with*() y encadenarlos.
• Ayudan a evitar estados inválidos a través de una estructura guiada.
• Ocultan la complejidad interna, lo que conduce a una mejor legibilidad.

​

Ejemplo

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

​

Trabajando con entidades

​

Uso de utilidades

​

Manejo de errores

• code: Un identificador corto y consistente para el tipo de error.
• message: Una descripción legible por humanos.
• details: (Opcional) Contexto adicional o metadatos.
• status: El código de estado HTTP, cuando esté disponible.

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

​

Códigos de error comunes

​

Mejores prácticas

• Valide la entrada antes de llamar a los métodos del SDK para evitar invalid_input.
• Verifique dos veces la autenticación cuando enfrente unauthorized o forbidden.
• Reintente en problemas transitorios como internal_error o service_unavailable.
• Use details para mostrar información de depuración útil en registros de desarrollo.

​

Pipeline de CI/CD

• 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 usando versionado semántico.
• Genera registros de cambios para total transparencia.

​

¿Quiere contribuir?

​

Licencia