SDK Node.js

Instalação e compatibilidade#

npm install @rebound-dlq/node

01 — Crie uma instância#

Configure o SDK uma vez e reutilize a instância nas operações da aplicação. O exemplo usa variáveis de ambiente para manter o segredo fora do código.

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

const dlq = new DlqWrapper({
  projectSecret: process.env.REBOUND_PROJECT_SECRET,
  onDelivery: event => console.log('Rebound:', event.type)
})

02 — Use na sua operação#

processarPagamento representa uma função que já existe na sua aplicação; dados é o payload necessário para investigar ou repetir essa operação. Troque os identificadores do fluxo pelos nomes da sua integração.

execute devolve o resultado da função quando ela funciona. Quando falha, tenta enfileirar a captura e relança o erro original. A chamada não espera a confirmação da API; use onDelivery para observar a entrega.

// dlq is the shared instance configured in your application.
// processarPagamento and dados belong to your business code.
try {
  const resultado = await dlq.execute(
    () => processarPagamento(dados),
    dados,
    {
      flowKey: 'pagarme-payments',
      flowLabel: 'Integração Pagarme',
      flowStep: 'create_charge'
    }
  )

  console.log('Pagamento processado:', resultado)
} catch (error) {
  console.error('Erro local tratado:', error.message)
  // The SDK attempts to queue the capture in the background.
  // Use onDelivery to observe API acknowledgement or delivery failure.
}

Use onde fizer sentido no seu código#

Estes são exemplos básicos de uso, não uma arquitetura obrigatória. Você pode chamar execute em um serviço, controller, worker, consumidor de fila ou job, conforme o framework e a organização da sua aplicação. A função envolvida continua devolvendo seu resultado ou lançando seu erro para o seu código tratar.

O catch permite tratar a falha localmente. Ele não confirma que a API recebeu a captura: a entrega ocorre em background e pode falhar ou ser bloqueada. Acompanhe onDelivery quando precisar observar esse resultado. Encerre a instância apenas no desligamento da aplicação, não após cada requisição.

Captura explícita e adaptadores#

ReboundClient.send exige source e recebe payload, error, metadata e contexto de fluxo. HTTPAdapter e KafkaAdapter oferecem sendToDLQ. O cliente/adaptadores armazenam um envelope com payload, source, metadata e timestamp; o wrapper mantém o payload original. Confira a estrutura antes de configurar o replay.

import { ReboundClient } from '@rebound-dlq/node'
const client = new ReboundClient({ projectSecret: process.env.REBOUND_PROJECT_SECRET })
await client.send({
  source: 'orders-worker', payload: { orderId: 'demo-001' },
  error: new Error('Payment timeout'), flowKey: 'orders.capture', flowStep: 'charge'
})

Configuração#

Entrega e encerramento#

flush aguarda a fila sem fechar o cliente. close impede novas capturas, tenta drenar e descarta o restante se o tempo acabar. Ambos devolvem completed, pending, delivered e dropped; os contadores são acumulados na instância.

Em serviços, reutilize a instância e integre close ao encerramento da aplicação após parar novas operações. O SDK não instala handlers globais de sinais. Uma finalização forçada pode perder itens em memória.