SDK do Midaz para TypeScript

​

Por que usar o SDK do Midaz para TypeScript?

• Segurança de tipos por design: suporte completo a TypeScript com definições de tipo precisas.
• Padrão builder: interfaces fluentes e legíveis para construir objetos complexos.
• Tratamento de erros: estratégias de recuperação e sinais de erro claros.
• Observabilidade incluída: tracing, métricas e logs, prontos para uso.
• Arquitetura em camadas: separação clara entre client, entities, API e models.
• Novas tentativas automáticas: políticas de nova tentativa configuráveis para falhas transitórias.
• Controles de concorrência: ferramentas integradas para executar tarefas em paralelo com throughput controlado.
• Rápido com cache: cache em memória para melhor desempenho.
• Validação estrita: detecte entradas inválidas cedo, com mensagens de erro claras.

​

Primeiros passos

​

Pré-requisito

• O SDK do Midaz para TypeScript requer TypeScript v5.8 ou posterior.

​

Instalando o SDK

npm install @lerianstudio/midaz-sdk

yarn add @lerianstudio/midaz-sdk

​

Autenticação

​

Autenticação com o 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')
);

​

Desenvolvimento local (sem autenticação)

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

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

​

Guia de início rápido

​

Criar um client

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

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

​

Criar um Ativo

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

​

Criar uma Conta

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

​

Criar uma Transação

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

​

Recuperação de erros

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

​

Limpar recursos

client.close();

​

Usando o Access Manager para autenticação

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

​

Arquitetura do SDK

• Interface do client: este é o ponto de entrada principal para os usuários do SDK. Ela gerencia a configuração, como API keys e ambientes. Ela inicializa os serviços de forma lazy e expõe toda a funcionalidade do SDK.
• Camada de serviços de entidade: esta camada reúne serviços específicos de domínio, como Contas, Ativos e Transações. Cada serviço oferece métodos consistentes: criar, obter, atualizar, excluir e listar. Cada serviço também adiciona operações especializadas para sua entidade.
• Camada de serviços principais: todos os serviços de entidade usam esses utilitários fundamentais. Eles cuidam de requisições HTTP, validação de entrada, processamento de erros, observabilidade, configuração e cache.

• Consistência por meio de padrões compartilhados entre os serviços.
• Escalabilidade via injeção de dependência e factories de serviço.
• Confiabilidade por meio de tratamento de erros aprimorado e respostas tipadas.
• Testabilidade com suporte para mocking, testes de integração e testes de contrato.

​

Padrão builder

• Informam os parâmetros com antecedência.
• Permitem definir campos opcionais com métodos .with*() e encadeá-los.
• Evitam estados inválidos por meio de uma estrutura guiada.
• Ocultam a complexidade interna para melhorar a legibilidade.

​

Exemplo

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

​

Trabalhando com entidades

​

Usando utilitários

​

Tratamento de erros

• code: um identificador curto e consistente para o tipo de erro.
• message: uma descrição legível para humanos.
• statusCode: o código de status HTTP, quando disponível.

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

​

Códigos de erro comuns

​

Boas práticas

• Valide a entrada antes de chamar métodos do SDK, para evitar invalid_input.
• Verifique sua autenticação quando receber unauthorized ou forbidden.
• Tente novamente em problemas transitórios como internal_error ou service_unavailable.
• Use statusCode e message para mostrar informações de depuração nos logs de desenvolvimento.

​

Pipeline de CI/CD

• Executa testes em várias versões do Node.js.
• Aplica qualidade de código com ESLint e Prettier.
• Mantém as dependências atualizadas com o Dependabot.
• Cuida dos releases automaticamente com versionamento semântico.
• Gera changelogs.

​

Quer contribuir?

​

Licença