@kruzer/idk

O IDK (Integration Development Kit) é um conjunto de bibliotecas e ferramentas instaladas como dependência em seus projetos para acelerar o desenvolvimento de integrações na plataforma Kruzer.

Ele fornece padrões, helpers e conectores que facilitam a criação, manutenção e escalabilidade das integrações, garantindo segurança e consistência.

Instalação

Adicione o IDK no seu projeto via npm:

npm install @kruzer/idk

Logger

Importe e instancie o logger para registrar logs com contexto de execução automático:

import { logger } from "@kruzer/idk";

logger.log({
  status: 'info',
  identifier: 'OrderProcess',
  content: { orderId: 12345, message: 'Pedido processado com sucesso' }
});

Descrição

  • A classe Logger automaticamente inclui o executionId da requisição atual, extraído do contexto Elastic APM, se disponível.
  • Se não houver contexto, o log é exibido diretamente no console.
  • Os logs são enviados em formato JSON, incluindo informações de tenant, projeto, gatilho e origem do log, conforme variáveis de ambiente configuradas:
    • API_ID
    • TENANT
    • PROJECT
    • TRIGGER
    • EXECUTION_ID

Parâmetros do método log

  • status (string): Indica o status do evento registrado, como 'info', 'error' ou 'success'.
  • identifier (string): Tag textual para facilitar a identificação do log no sistema.
  • content (any): Dados detalhados do evento a serem logados. Pode ser qualquer objeto ou valor serializável.

Considerações

  • Objetos muito grandes são truncados automaticamente para até 2MB.
  • Arrays com mais de 100 itens e objetos com mais de 100 chaves são reduzidos para evitar logs excessivos.
  • Ideal para uso em projetos Node.js que requerem logging estruturado e rastreamento distribuído integrado ao Elastic APM.

RestDataSource

A classe RestDataSource é uma implementação especializada da classe base DataSource que permite realizar requisições HTTP REST utilizando configurações pré-definidas e contexto da plataforma Kruzer.

Importação 

import { RestDataSource } from "@kruzer/idk";

Instanciação 

const restSource = new RestDataSource('nomeDaFonte', {
  // opções REST opcionais, ex:
  body: { key: 'value' },
  headers: { 'Content-Type': 'application/json' }
});

  • Parâmetros do construtor:

    • name (string): Nome do data source REST configurado na plataforma.
    • options? (RestOptions): Configurações padrão para as requisições, tais como corpo (body), headers e outras opções.

Método: request

Realiza uma requisição POST para o endpoint configurado da fonte REST, enviando o alias da requisição, corpo e opções adicionais.

const response = await restSource.request('aliasDaRequisicao', {
  body: { param1: 'valor1' },
  headers: { Authorization: 'Bearer token' }
});

  • Parâmetros:

    • alias (string): Identificador da operação ou recurso que será invocado no backend.
    • options? (RestOptions): Opções específicas para esta requisição que podem sobrescrever as opções padrão da instância.

  • Retorno:

    • Promise com o dado retornado da API (response.data).

Considerações

  • O cabeçalho da requisição inclui automaticamente o token de autenticação e informações de contexto como tenant, extraídos do ambiente e contexto de execução.
  • As opções da requisição são mescladas com as opções padrão da instância, com prioridade para as opções passadas no método request.
  • Utiliza axios para execução das requisições HTTP.
  • Indicado para integrações onde a fonte de dados REST é gerenciada pela plataforma Kruzer e se deseja garantir contexto e autenticação automática.

MongoDbDataSource

A classe MongoDbDataSource é uma implementação especializada da classe base DataSource que permite executar comandos no banco de dados MongoDB através da plataforma Kruzer, utilizando configurações e contexto pré-definidos.

Importação 

import { MongoDbDataSource } from "@kruzer/idk";

Instanciação 

const mongoSource = new MongoDbDataSource('nomeDaFonte');

  • Parâmetros do construtor:

    • name (string): Nome do data source MongoDB configurado na plataforma.

Método: command

Executa um comando no MongoDB via POST para o endpoint configurado, enviando o alias do comando e opções específicas.

const result = await mongoSource.command('aliasDoComando', {
  filter: { campo: 'valor' },
  limit: 10
});

  • Parâmetros:

    • alias (string): Identificador do comando e collection MongoDB a ser executado no backend.
    • options? (any): Opções específicas para este comando que podem sobrescrever as opções padrão da instância.

  • Retorno:

    • Promise com o resultado retornado pela API (response.data).

  • Tratamento de erro:

    • Em caso de falha, lança um erro contendo a mensagem detalhada da resposta da API ou mensagem genérica.

Considerações

  • O cabeçalho da requisição inclui automaticamente o token de autenticação e informações de contexto como tenant, extraídos do ambiente e contexto de execução.
  • As opções do comando são mescladas com as opções padrão da instância, com prioridade para as opções passadas no método command.
  • Utiliza axios para execução das requisições HTTP.
  • Indicado para integrações que executam comandos MongoDB gerenciados pela plataforma Kruzer, garantindo contexto e autenticação automáticos.

MsSqlDataSource

A classe MsSqlDataSource é uma implementação especializada da classe base DataSource que permite executar comandos e consultas SQL no banco Microsoft SQL Server através da plataforma Kruzer, utilizando configurações e contexto pré-definidos.

Importação 

import { MsSqlDataSource } from "@kruzer/idk";

Instanciação 

const mssqlSource = new MsSqlDataSource('nomeDaFonte');

  • Parâmetros do construtor:

    • name (string): Nome do data source MSSQL configurado na plataforma.

Método: command

Executa um comando MSSQL via POST para o endpoint configurado, enviando o alias do comando e opções específicas.

const result = await mssqlSource.command('aliasDoComando', {
  // opções específicas do comando
});

  • Parâmetros:

    • alias (string): Identificador do comando MSSQL a ser executado no backend.
    • options? (MsSqlOptions): Opções específicas para este comando que podem sobrescrever as opções padrão da instância.

  • Retorno:

    • Promise com o resultado retornado pela API (response.data).

Método: query

Executa uma consulta SQL direta via POST para o endpoint configurado, enviando a query e opções adicionais.

const result = await mssqlSource.query('SELECT * FROM tabela WHERE id = 1', {
  // opções específicas da consulta
});

  • Parâmetros:

    • query (string): Consulta SQL a ser executada.
    • options? (MsSqlOptions): Opções específicas para esta consulta que podem sobrescrever as opções padrão da instância.

  • Retorno:

    • Promise com o resultado retornado pela API (response.data).

Considerações

  • O cabeçalho da requisição inclui automaticamente o token de autenticação e informações de contexto como tenant, extraídos do ambiente e contexto de execução.
  • As opções do comando ou consulta são mescladas com as opções padrão da instância, com prioridade para as opções passadas nos métodos.
  • Utiliza axios para execução das requisições HTTP.
  • Indicado para integrações que executam comandos e queries MSSQL gerenciados pela plataforma Kruzer, garantindo contexto e autenticação automáticos.

MySqlDataSource

A classe MySqlDataSource é uma implementação especializada da classe base DataSource que permite executar múltiplos comandos SQL, inserções em lote e testes de conectividade (ping) no banco MySQL através da plataforma Kruzer, utilizando contexto e autenticação automáticos.

Importação 

import { MySqlDataSource } from "@kruzer/idk";

Instanciação 

const mySqlSource = new MySqlDataSource('nomeDaFonte');

  • Parâmetros do construtor:

    • name (string): Nome do data source MySQL configurado na plataforma.

Método: command

Executa múltiplos comandos SQL enviados em array via POST para o endpoint /multi.

const commands: MySQLCommand[] = [
  { sql: "UPDATE tabela SET campo = ? WHERE id = ?", params: ["valor", 1] },
  { sql: "DELETE FROM tabela WHERE id = ?", params: [2] }
];
const response = await mySqlSource.command(commands);

  • Parâmetros:

    • requestBody (Array): Lista de comandos SQL com parâmetros a serem executados.

  • Retorno:

    • Promise com a resposta agregada dos comandos (MySQLMultiCommandResponse).

Método: multiInsert

Realiza inserções em lote via POST para o endpoint /multi/insert.

const insertData: MySQLMultiInsert = {
  table: "tabela",
  rows: [
    { campo1: "valor1", campo2: "valor2" },
    { campo1: "valor3", campo2: "valor4" }
  ]
};
const response = await mySqlSource.multiInsert(insertData);

  • Parâmetros:

    • requestBody (MySQLMultiInsert): Dados para inserção múltipla.

  • Retorno:

    • Promise com a resposta da inserção múltipla (MySQLMultiCommandResponse).

Método: ping

Realiza um teste de conectividade via POST para o endpoint /ping.

const pingRequest: MySQLPing = { timeout: 5000 };
const isAlive = await mySqlSource.ping(pingRequest);

  • Parâmetros:

    • requestBody (MySQLPing): Configurações para o ping, como timeout.

  • Retorno:

    • Promise com boolean indicando se o banco respondeu (true) ou não (false).

Considerações

  • Todas as requisições incluem automaticamente o token de autenticação e informações de contexto como tenant, extraídos do ambiente e contexto de execução.
  • Utiliza axios para execução das requisições HTTP.
  • Indicado para integrações que manipulam comandos MySQL complexos, inserções em lote e verificações de saúde do banco, mantendo contexto e autenticação automáticos.

OracleDataSource

A classe OracleDataSource é uma implementação especializada da classe base DataSource que permite executar comandos e consultas SQL no banco Oracle através da plataforma Kruzer, utilizando configurações e contexto pré-definidos.

Importação 

import { OracleDataSource } from "@kruzer/idk";

Instanciação 

const oracleSource = new OracleDataSource('nomeDaFonte');

  • Parâmetros do construtor:

    • name (string): Nome do data source Oracle configurado na plataforma.

Método: command

Executa um comando Oracle via POST para o endpoint configurado, enviando o alias do comando e opções específicas.

const result = await oracleSource.command('aliasDoComando', {
  // opções específicas do comando
});

  • Parâmetros:

    • alias (string): Identificador do comando Oracle a ser executado no backend.
    • options? (OracleOptions): Opções específicas para este comando que podem sobrescrever as opções padrão da instância.

  • Retorno:

    • Promise com o resultado retornado pela API (response.data).

Método: query

Executa uma consulta SQL direta via POST para o endpoint configurado, enviando a query e opções adicionais.

const result = await oracleSource.query('SELECT * FROM tabela WHERE id = 1', {
  // opções específicas da consulta
});

  • Parâmetros:

    • query (string): Consulta SQL a ser executada.
    • options? (OracleOptions): Opções específicas para esta consulta que podem sobrescrever as opções padrão da instância.

  • Retorno:

    • Promise com o resultado retornado pela API (response.data).

Considerações

  • O cabeçalho da requisição inclui automaticamente o token de autenticação e informações de contexto como tenant, extraídos do ambiente e contexto de execução.
  • As opções do comando ou consulta são mescladas com as opções padrão da instância, com prioridade para as opções passadas nos métodos.
  • Utiliza axios para execução das requisições HTTP.
  • Indicado para integrações que executam comandos e queries Oracle gerenciados pela plataforma Kruzer, garantindo contexto e autenticação automáticos.

Copyright © 2025 kruzer | All Rights Reserved