Rebound DLQ for Node.js

O @rebound-dlq/node é o SDK oficial em Node.js para integração com a plataforma Rebound DLQ.

Este pacote permite capturar falhas em integrações (APIs de terceiros, pagamentos, envio de e-mails, etc.) de forma transparente para a sua aplicação Node.js. Sem travar sua regra de negócio e sem adicionar latência. Quando uma operação falha, o SDK captura o payload, criptografa a informação e envia o evento em plano de fundo (background) para a sua conta no Rebound DLQ, aplicando estratégias de retry exponencial automaticamente se houver instabilidade na rede.

Por que usar o Rebound DLQ?

• ⚡ Zero Latência (In-Memory Queue): A aplicação não espera a resposta do envio do log para a nossa infraestrutura. A execução ocorre inteiramente em memória e em background, liberando o processo Node.js principal na hora (O(1)).
• 🛡️ Segurança e Criptografia Local: Todo o payload de erro é criptografado localmente na sua máquina (usando AES-256) antes mesmo de trafegar pela rede. Seus dados chegam anônimos na nossa infraestrutura, e somente você consegue descriptografá-los com a sua chave secreta.
• 🔁 Resiliência e Retentativa Automática: Falhas de rede ou indisponibilidade? O SDK mantém o evento a salvo em memória e aplica backoff exponencial para garantir a entrega quando a conexão for reestabelecida.

⚠️ Atenção: Este SDK requer uma conta ativa na plataforma Rebound DLQ.

Instalação

Abra o terminal e instale o pacote via npm, yarn ou pnpm:

npm install @rebound-dlq/node

Configuração Segura

O SDK só precisa da chave de integração do seu projeto (projectSecret).

Prática Recomendada: Nunca exponha (hard-code) a sua chave diretamente no código-fonte. Armazene a sua chave projectSecret de forma segura utilizando variáveis de ambiente (ex: arquivo .env).

# Arquivo .env
REBOUND_PROJECT_SECRET="sk_dev_sua_chave_secreta_aqui"

Dica de Ambiente:

• Chaves iniciadas com sk_dev_ enviarão eventos automaticamente para o ambiente de testes/sandbox.
• Chaves iniciadas com sk_live_ enviarão eventos para o ambiente de produção.

Uso Básico

A forma ideal de utilizar o SDK é encapsular a sua função com o método .execute() oferecido pela classe DlqWrapper.

Se atente à inicialização e uso:

import { DlqWrapper } from '@rebound-dlq/node';

// Inicializa o SDK consumindo de variáveis de ambiente
const dlq = new DlqWrapper({
  projectSecret: process.env.REBOUND_PROJECT_SECRET,
});

// A função que se conecta ao seu provedor ou ao seu banco de dados (que pode falhar)
async function processarPagamento(dados) {
  if (dados.valor > 1000) {
    throw new Error('Saldo insuficiente na operadora do cartão');
  }
  return 'Sucesso!';
}

async function main() {
  // Os dados de contexto que você gostaria de analisar depois se algo der errado
  const payloadQueSeraSalvoNaDLQ = {
    userId: '123',
    valor: 5000,
    tentativa: 1,
    modulo: 'Checkout',
  };

  try {
    console.log("Iniciando transação...");

    // Protegemos a função com o wrapper. Se der erro dentro de processarPagamento,
    // o dlq envia os detalhes do erro E o payloadQueSeraSalvoNaDLQ para o Rebound automatically!
    const resultado = await dlq.execute(
      () => processarPagamento(payloadQueSeraSalvoNaDLQ),
      payloadQueSeraSalvoNaDLQ
    );

    console.log('Finalizado com:', resultado);

  } catch (erro) {
    // A aplicação não morre; o erro é lançado apenas para seu tratamento habitual
    console.log('Aconteceu um erro previsto na aplicação:', erro.message);
  }
}

main();

O que acontece por baixo dos panos neste exemplo?

1. Ao chamar .execute(), se o processarPagamento lançar qualquer exceção.
2. Essa exceção é capturada sem dor.
3. A variável payloadQueSeraSalvoNaDLQ entra na memória RAM do SDK.
4. É processada criptografia local AES-256 no dado, utilizando a sua chave.
5. Em Background, um processo envia de forma segura este evento para a plataforma Rebound, garantindo entrega do Dead Letter Queue para reprocessamento futuro ou simples visualização pela Dashboard.

Suporte

Em caso de dúvidas, problemas de implementação ou bugs, abra um chamado pela Dashboard oficial do Rebound Platform.

Feito com ❤️ por [Codify Labs] / [Rebound DLQ].