Rebound DLQ — Node.js SDK

SDK oficial em Node.js para integrar sua aplicação com a plataforma Rebound DLQ.

Capture falhas, registre eventos de erro e garanta rastreabilidade das suas filas mortas — sem esperar a resposta de rede no fluxo principal.

Por que usar?

• Envio em background — serialização e criptografia ocorrem localmente; a entrega de rede ocorre em background.
• Criptografia local AES-256 — o payload é criptografado antes de sair do seu processo.
• Entrega resiliente e limitada — retry para falhas temporárias, com timeout, backoff, jitter e orçamento finito.
• Respeito aos limites — buffer ou descarte conforme a política retornada pela API; nenhuma tentativa autoriza excedentes por conta própria.

Runtime: Node.js 20 ou superior.

Pré-requisito: uma conta e um projeto ativos em rebound-dlq.com.

Licença

Este SDK é distribuído sob uma licença proprietária de uso limitado. Ele pode ser usado para integrar aplicações ao Rebound DLQ Cloud ou Self-hosted, mas não pode ser redistribuído, revendido, publicado em versões modificadas ou usado para criar produto concorrente sem autorização prévia da Codify Labs.

Consulte o arquivo LICENSE para os termos completos.

Instalação

npm install @rebound-dlq/node

Configuração

A única configuração obrigatória é o projectSecret, obtido no painel da plataforma Rebound DLQ.

Nunca exponha a chave no código-fonte. Use variáveis de ambiente:

REBOUND_PROJECT_SECRET="seu_project_secret_aqui"
# Opcional: use apenas em ambientes self-hosted.
REBOUND_BASE_URL="https://rebound.seu-dominio.com/api/v1"

Se REBOUND_BASE_URL não for informada, o SDK continua usando automaticamente a API cloud oficial:

https://api.rebound-dlq.com/api/v1

Para compatibilidade, o SDK ainda aceita baseUrl e endpoint no código, além de REBOUND_API_ENDPOINT e REBOUND_DLQ_BASE_URL por variável de ambiente. A prioridade é:

1. reboundUrl, baseUrl ou endpoint informado no código, nessa ordem.
2. REBOUND_BASE_URL, REBOUND_DLQ_BASE_URL ou REBOUND_API_ENDPOINT, nessa ordem.
3. API cloud padrão do Rebound DLQ.

Agrupamento por fluxo

Agora o SDK também pode ajudar a agrupar eventos DLQ por fluxo de integração na plataforma.

Isso é útil quando o seu cliente quer enxergar, por exemplo, apenas os erros do fluxo Pagarme, ERP, Webhook de pedidos ou qualquer outro processo operacional.

Os campos usados pela plataforma são:

| Campo | Obrigatório | Descrição | |---|---|---| | flowKey | Não; necessário para associar o evento a um fluxo | Identificador técnico e estável do fluxo. Ex.: pagarme-payments. | | flowLabel | Não | Nome amigável exibido no painel. Ex.: Integração Pagarme. | | flowStep | Não | Etapa específica do fluxo. Ex.: create_charge, payment_webhook, capture_receivables. |

Regra de agrupamento

• Se chegar um evento com um flowKey já existente naquele projeto, ele é agrupado no mesmo fluxo.
• Se o flowKey ainda não existir, a plataforma cria o fluxo automaticamente.
• Se o evento não enviar dados de fluxo, ele continua funcionando normalmente, como já funciona hoje.

Exemplo recomendado de nomenclatura

{
  flowKey: 'pagarme-payments',
  flowLabel: 'Integração Pagarme',
  flowStep: 'payment_webhook'
}

Dica: trate flowKey como identificador estável. Evite usar textos que mudam com frequência.

Interfaces disponíveis

DlqWrapper — recomendado

Encapsula uma função síncrona ou assíncrona. Se ela lançar uma exceção, o evento de erro é capturado, criptografado e enviado automaticamente em background.

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

const dlq = new DlqWrapper({
  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
  // Opcional: use apenas para apontar o SDK para uma API self-hosted.
  // reboundUrl: 'https://rebound.seu-dominio.com/api/v1',
});

Parâmetros:

| Campo | Obrigatório | Descrição | |---|---|---| | projectSecret | ✅ Sim | Chave secreta do projeto, usada para autenticação e criptografia local. | | reboundUrl | Não | URL base da API Rebound. Use somente em ambientes self-hosted; se não for informada, o SDK usa as variáveis de ambiente ou a API cloud padrão. | | baseUrl / endpoint | Não | Aliases legados de reboundUrl. endpoint também aceita a URL completa com /dlq-injestion. |

Uso:

const resultado = await dlq.execute(() => minhaFuncaoQuePodeFalhar(dados), dados);

O erro original é sempre relançado para o seu tratamento normal. O SDK apenas captura, criptografa e envia o evento em background.

Exemplo completo:

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

const dlq = new DlqWrapper({
  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
});

async function processarPagamento(dados: { userId: string; valor: number }) {
  if (dados.valor > 10000) {
    throw new Error('Limite excedido na operadora');
  }
  return 'aprovado';
}

try {
  const resultado = await dlq.execute(
    () => processarPagamento({ userId: 'u-123', valor: 15000 }),
    { userId: 'u-123', valor: 15000 },
  );
} catch (err) {
  // O erro original é relançado. O SDK tenta enfileirar a captura para entrega em background.
  console.error((err as Error).message);
}

DlqWrapper com fluxo

Se você quiser agrupar o evento por fluxo usando o DlqWrapper, passe um terceiro parâmetro opcional com o contexto do fluxo.

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

const dlq = new DlqWrapper({
  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
});

await dlq.execute(
  () => processarPagamento({ userId: 'u-123', valor: 15000 }),
  {
    userId: 'u-123',
    valor: 15000,
  },
  {
    flowKey: 'pagarme-payments',
    flowLabel: 'Integração Pagarme',
    flowStep: 'create_charge',
  },
);

Se você não passar o terceiro parâmetro, o evento continua sendo enviado normalmente, sem vínculo com fluxo.

ReboundClient + adapters — uso avançado

Para enviar eventos manualmente ou usar com adapters (HTTP, Kafka etc.).

import { ReboundClient, HTTPAdapter } from '@rebound-dlq/node';

const client = new ReboundClient({
  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
  // Opcional: use apenas para apontar o SDK para uma API self-hosted.
  // reboundUrl: 'https://rebound.seu-dominio.com/api/v1',
});

const httpDlq = new HTTPAdapter(client);

await httpDlq.sendToDLQ({
  payload: { orderId: 'ORD-1001', amount: 99.9 },
  error: new Error('Payment gateway timeout'),
  flowKey: 'checkout-payments',
  flowLabel: 'Checkout de pagamentos',
  flowStep: 'gateway_authorization',
  metadata: {
    endpoint: '/api/payments',
    method: 'POST',
    tenantId: 'acme',
  }
});

Parâmetros do ReboundClient:

| Campo | Obrigatório | Descrição | |---|---|---| | projectSecret | ✅ Sim | Chave secreta do projeto, usada para autenticação e criptografia local. | | reboundUrl | Não | URL base da API Rebound. Use somente em ambientes self-hosted; se não for informada, o SDK usa as variáveis de ambiente ou a API cloud padrão. | | baseUrl / endpoint | Não | Aliases legados de reboundUrl. endpoint também aceita a URL completa com /dlq-injestion. |

Exemplo com fluxo usando HTTPAdapter

import { ReboundClient, HTTPAdapter } from '@rebound-dlq/node';

const client = new ReboundClient({
  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
});

const httpDlq = new HTTPAdapter(client);

await httpDlq.sendToDLQ({
  payload: {
    orderId: 'ORD-1001',
    amount: 99.9,
    customerId: 'cus_123',
  },
  error: new Error('Payment gateway timeout'),
  flowKey: 'pagarme-payments',
  flowLabel: 'Integração Pagarme',
  flowStep: 'create_charge',
  metadata: {
    endpoint: '/api/payments',
    method: 'POST',
    tenantId: 'acme',
  },
});

Exemplo com fluxo usando KafkaAdapter

import { ReboundClient, KafkaAdapter } from '@rebound-dlq/node';

const client = new ReboundClient({
  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
});

const kafkaDlq = new KafkaAdapter(client);

await kafkaDlq.sendToDLQ({
  payload: {
    topic: 'payments.events',
    partition: 2,
    key: 'order-1001',
    message: { orderId: 'ORD-1001', status: 'failed' },
  },
  error: new Error('Kafka publish timeout'),
  flowKey: 'pagarme-payments',
  flowLabel: 'Integração Pagarme',
  flowStep: 'payment_webhook',
  metadata: {
    topic: 'payments.events',
    consumerGroup: 'payments-worker',
  },
});

Resumo prático de uso

• Use DlqWrapper quando quiser a integração mais simples possível.
• Use ReboundClient + adapters quando quiser separar melhor payload e metadata.
• Para agrupamento por fluxo, envie flowKey, flowLabel e flowStep como campos opcionais separados do payload.
• metadata continua existindo para contexto técnico adicional, sem misturar regra de agrupamento com o payload do usuário.

Comportamento automático

O SDK gerencia entrega, retry e limites de plano de forma totalmente automática, sem configuração adicional.

| Situação | O que o SDK faz | |---|---| | Sucesso na entrega | Remove o evento da fila | | Falha de rede / erro transiente | Retry com backoff, jitter, timeout e orçamento finito | | Bloqueio com política de descarte | Descarta eventos; novos envios podem disparar reconsulta do estado | | Bloqueio temporário com política de buffer | Retém eventos dentro da janela e dos limites locais, consultando a retomada | | Excedente autorizado pela API | Envia normalmente; a API controla a contabilização | | Conta desbloqueada / upgrade | Retoma o envio automaticamente, sem reiniciar o processo |

A política de limite e cobrança extra é definida na sua conta na plataforma, não no SDK.

Observações operacionais

• A fila é in-memory: eventos não sobrevivem a restart do processo.
• Para workloads efêmeros, prefira processos com shutdown gracioso.
• Use onDelivery para observar entrega, retry, buffer, retomada e descarte. Sem callback, descartes são registrados no console.

Suporte

Dúvidas de integração ou comportamento? Abra um chamado pela plataforma oficial em rebound-dlq.com.

Feito por Codify Labs / Rebound DLQ.

Confiabilidade e encerramento

await client.send() confirma apenas o enfileiramento local. A fila é volátil: uma interrupção abrupta do processo perde eventos pendentes. Não existe garantia de entrega ilimitada ou armazenamento em disco. O wrapper sempre relança o valor original lançado pela aplicação.

Cada client/wrapper possui sua própria fila. Os padrões são: timeout de 10 segundos por requisição, até 5 retries, 1.000 eventos/10 MiB retidos, payload JSON de até 256 KiB e vida máxima de 15 minutos. timeout, maxRetries, maxQueueSize, maxQueueBytes, maxPayloadBytes e maxEventAgeMs permitem ajustes dentro dos limites validados pelo SDK. Excesso de capacidade rejeita novos envios; o wrapper registra a falha sem substituir o erro original.

HTTP 408/425/429/5xx e erros de rede permitem retry; outras rejeições HTTP são definitivas. O SDK respeita Retry-After. Bloqueios de plano usam buffer temporário de até 250 eventos ou descarte, conforme a API. Buffer, itens em trânsito e retries compartilham o limite de memória da fila.

const client = new ReboundClient({
  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
  onDelivery(event) {
    // delivered, dropped, retry, blocked ou resumed; nunca contém a chave/payload.
    console.log(event.type, event.eventId, event.reason);
  },
});

await client.send({ source: 'orders', payload: { orderId: 123 } });
const result = await client.close(10_000);
// close para novos envios, aguarda o prazo e descarta o restante.
// delivered/dropped são contadores acumulados; completed indica drenagem dentro do prazo.
console.log(result.completed, result.pending, result.delivered, result.dropped);

flush(timeoutMs) aguarda a fila sem fechar o client. Os mesmos métodos existem no wrapper e nos adapters. Mesmo com completed: true, confira dropped: drenagem não significa que todos os eventos foram entregues. Em workers/CLI/serverless, aguarde flush/close antes de terminar a execução; o SDK não instala handlers globais de shutdown.

Strings são serializadas como JSON; BigInt vira string e referências circulares viram [Circular]. O wrapper mantém o payload original para replay; os adapters mantêm o envelope { payload, source, metadata, timestamp }. Apenas o payload é criptografado; dados de erro e contexto de fluxo seguem no envelope autenticado. Use HTTPS fora de desenvolvimento local.

O agrupamento legado de eventos sem fluxo é preservado. Eventos com flowKey passam a separar fluxo e etapa, podendo iniciar novos grupos ao atualizar o SDK. fingerprintVersion: 'v2' permite optar pelo algoritmo comum para todas as interfaces; essa opção também inicia novos grupos.

Cada ocorrência recebe um eventId UUID v4, preservado em todas as tentativas. A API atualizada deduplica por projeto/eventId por 7 dias, sem repetir ocorrência ou consumo. Para essa proteção, sua instalação precisa da API Rebound DLQ 1.6.0 ou superior com a migração de receipts aplicada. Em instalações self-hosted, atualize a API e execute as migrações antes de atualizar o SDK. APIs anteriores não oferecem essa garantia de deduplicação.

Atualização para 1.0.0

Consulte o guia de migração para atualizar a partir de 0.2.x e o histórico de versões para as mudanças desta versão.