@rebound-dlq/node 0.2.4 → 0.2.5

package/README.md

@@ -1,87 +1,50 @@
-# Rebound DLQ for Node.js
+# Rebound DLQ — Node.js SDK
 
 [![NPM Version](https://img.shields.io/npm/v/@rebound-dlq/node)](https://www.npmjs.com/package/@rebound-dlq/node)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-O **@rebound-dlq/node** e o SDK oficial em Node.js para integrar sua aplicacao com a plataforma **[Rebound DLQ](https://rebound-dlq.com)**.
+SDK oficial em Node.js para integrar sua aplicação com a plataforma **[Rebound DLQ](https://rebound-dlq.com)**.
 
-Ele captura falhas da sua aplicacao, criptografa o payload localmente e envia o evento para a sua conta em background, sem travar a regra de negocio. A fila e mantida em memoria e o SDK ja entende os cenarios de rede instavel, limite de plano, overage e retomada automatica apos upgrade ou mudanca de configuracao da conta.
+Capture falhas, registre eventos de erro e garanta rastreabilidade das suas filas mortas — tudo sem impactar a performance da sua aplicação.
 
-## Por que usar o Rebound DLQ?
+---
+
+## Por que usar?
 
-- **Zero latencia no fluxo principal**: o evento e enfileirado em memoria e a sua aplicacao segue executando sem esperar round-trip de rede.
-- **Criptografia local AES-256**: o payload e criptografado antes de sair do seu processo.
-- **Entrega resiliente**: falhas de rede e indisponibilidade temporaria continuam usando retry com backoff exponencial.
-- **Comportamento orientado ao plano da conta**: o SDK sabe quando deve continuar, quando deve aguardar e quando deve descartar eventos acima do limite.
-- **Retomada automatica**: quando a conta faz upgrade ou libera overage, o SDK volta a enviar sozinho.
+- **Zero latência no fluxo principal** — o evento é enfileirado em memória e a aplicação segue sem esperar resposta de rede.
+- **Criptografia local AES-256** — o payload é criptografado antes de sair do seu processo.
+- **Entrega resiliente** — retry automático com backoff exponencial em caso de falha de rede.
+- **Sem config extra** — o comportamento de retry, buffer e retomada é totalmente automático, determinado pela configuração da conta na plataforma.
 
-> Importante: este SDK requer uma conta e um projeto ativos no Rebound DLQ.
+> **Pré-requisito:** uma conta e um projeto ativos em [rebound-dlq.com](https://rebound-dlq.com).
 
-## Instalacao
+---
+
+## Instalação
 
 ```bash
 npm install @rebound-dlq/node
 ```
 
-## Requisitos
-
-Para usar o SDK com o comportamento completo desta versao:
-
-- uma chave valida do projeto
-- uma API Rebound atualizada, com suporte a:
-  - `POST /dlq-injestion`
-  - `POST /dlq-injestion/runtime-state`
-  - autenticacao HMAC com `x-api-key`, `x-sdk-timestamp` e `x-sdk-signature`
-  - resposta estruturada de bloqueio por limite de plano
+---
 
-Se voce usa a plataforma oficial atualizada da Rebound, nao precisa configurar nada extra no cliente para esse fluxo. O comportamento de buffer, descarte e retomada e automatico.
+## Configuração
 
-## Configuracao segura
+A única configuração obrigatória é o `projectSecret`, obtido no painel da plataforma Rebound DLQ.
 
-Nunca exponha a chave diretamente no codigo-fonte. Use variaveis de ambiente:
+Nunca exponha a chave no código-fonte. Use variáveis de ambiente:
 
 ```env
 REBOUND_PROJECT_SECRET="seu_project_secret_aqui"
 ```
 
-## Executando os examples do repositorio
-
-Os arquivos em `examples/` foram deixados simples para teste local. Cada example tem duas variaveis no topo do arquivo:
-
-- `PROJECT_SECRET`
-- `API_ENDPOINT`
-
-Edite esses valores diretamente no arquivo que voce quer testar e depois rode o script.
-
-```bash
-npm run example:wrapper
-npm run example:http
-npm run example:kafka
-npm run example:internal
-```
-
-Se preferir, voce tambem pode chamar o runner diretamente:
-
-```bash
-node scripts/run-example.cjs wrapper
-```
-
-Os exemplos encerram sozinhos apos uma pequena janela de observacao para nao ficarem presos em retries de background quando a API estiver offline. Se quiser alterar isso, use `REBOUND_EXAMPLE_GRACE_MS`.
-
-### Fluxo unico de configuracao
-
-O SDK agora trabalha com um fluxo unico:
-
-- `projectSecret` para autenticar e derivar a criptografia local
-- `endpoint` para definir para qual API Rebound os eventos devem ser enviados
-
-Nao existe mais diferenca publica entre ambiente de teste e producao dentro do SDK. Se voce quiser apontar para outra API, basta informar `endpoint` explicitamente.
+---
 
-## Interfaces disponiveis
+## Interfaces disponíveis
 
-### 1. `DlqWrapper`
+### `DlqWrapper` — recomendado
 
-Melhor opcao para encapsular uma funcao que pode falhar.
+Encapsula qualquer função assíncrona. Se ela lançar uma exceção, o evento de erro é capturado, criptografado e enviado automaticamente em background.
 
 ```ts
 import { DlqWrapper } from '@rebound-dlq/node';
@@ -91,38 +54,21 @@ const dlq = new DlqWrapper({
 });
 ```
 
-#### Parametros
+**Parâmetros:**
 
-| Campo | Obrigatorio | Descricao |
-| --- | --- | --- |
-| `projectSecret` | Sim | Chave secreta do projeto usada para criptografia local e autenticacao do SDK. |
-| `endpoint` | Nao | URL base da sua API Rebound, por exemplo `https://api.suaempresa.com/api/v1`. O SDK monta `/dlq-injestion` automaticamente, mas tambem aceita a URL completa por compatibilidade. |
-| `maxFailures` | Nao | Mantido apenas por compatibilidade retroativa. Atualmente nao altera o comportamento da fila. |
+| Campo | Obrigatório | Descrição |
+|---|---|---|
+| `projectSecret` | ✅ Sim | Chave secreta do projeto, usada para autenticação e criptografia local. |
 
-### 2. `ReboundClient`
-
-Melhor opcao para enviar payloads DLQ manualmente ou usar os adapters.
+**Uso:**
 
 ```ts
-import { ReboundClient } from '@rebound-dlq/node';
-
-const client = new ReboundClient({
-  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
-  endpoint: process.env.REBOUND_API_ENDPOINT,
-});
+const resultado = await dlq.execute(() => minhaFuncaoQuePodefFalhar(dados), dados);
 ```
 
-#### Parametros
-
-| Campo | Obrigatorio | Descricao |
-| --- | --- | --- |
-| `projectSecret` | Sim | Secret do projeto criado no painel, usado para autenticar as chamadas do SDK. |
-| `endpoint` | Nao | URL base da sua API Rebound, por exemplo `https://api.suaempresa.com/api/v1`. O SDK monta `/dlq-injestion` automaticamente, mas tambem aceita a URL completa por compatibilidade. |
-| `timeout` | Nao | Campo reservado no tipo de configuracao. Atualmente nao altera o transporte. |
-
-Quando voce usa `ReboundClient` ou um adapter, o SDK converte o payload manual para o contrato de ingestao da API, gera `fingerprint`, criptografa o envelope localmente e envia no mesmo formato aceito pelo backend.
+O erro original é sempre relançado para o seu tratamento normal. O SDK apenas captura, criptografa e envia o evento em background.
 
-## Uso recomendado com `DlqWrapper`
+**Exemplo completo:**
 
 ```ts
 import { DlqWrapper } from '@rebound-dlq/node';
@@ -131,47 +77,29 @@ const dlq = new DlqWrapper({
   projectSecret: process.env.REBOUND_PROJECT_SECRET!,
 });
 
-async function processarPagamento(dados: {
-  userId: string;
-  valor: number;
-  tentativa: number;
-  modulo: string;
-}) {
-  if (dados.valor > 1000) {
-    throw new Error('Saldo insuficiente na operadora do cartao');
+async function processarPagamento(dados: { userId: string; valor: number }) {
+  if (dados.valor > 10000) {
+    throw new Error('Limite excedido na operadora');
   }
-
-  return 'Sucesso';
+  return 'aprovado';
 }
 
-async function main() {
-  const payload = {
-    userId: '123',
-    valor: 5000,
-    tentativa: 1,
-    modulo: 'Checkout',
-  };
-
-  try {
-    const resultado = await dlq.execute(() => processarPagamento(payload), payload);
-    console.log('Resultado:', resultado);
-  } catch (erro) {
-    console.error('Erro de negocio capturado pela aplicacao:', (erro as Error).message);
-  }
+try {
+  const resultado = await dlq.execute(
+    () => processarPagamento({ userId: 'u-123', valor: 15000 }),
+    { userId: 'u-123', valor: 15000 },
+  );
+} catch (err) {
+  // erro relançado normalmente — o SDK já registrou o evento
+  console.error((err as Error).message);
 }
-
-main();
 ```
 
-### O que acontece nesse fluxo
+---
 
-1. Sua funcao falha e a excecao e capturada.
-2. O payload e criptografado localmente com AES-256.
-3. O evento e colocado em uma fila em memoria.
-4. O SDK envia o evento em background com autenticacao HMAC.
-5. O erro original continua sendo relancado para o seu tratamento normal.
+### `ReboundClient` + adapters — uso avançado
 
-## Uso manual com `ReboundClient`
+Para enviar eventos manualmente ou usar com adapters (HTTP, Kafka etc.).
 
 ```ts
 import { ReboundClient, HTTPAdapter } from '@rebound-dlq/node';
@@ -183,10 +111,7 @@ const client = new ReboundClient({
 const httpDlq = new HTTPAdapter(client);
 
 await httpDlq.sendToDLQ({
-  payload: {
-    orderId: 'ORD-1001',
-    amount: 99.9,
-  },
+  payload: { orderId: 'ORD-1001', amount: 99.9 },
   error: new Error('Payment gateway timeout'),
   metadata: {
     endpoint: '/api/payments',
@@ -196,110 +121,42 @@ await httpDlq.sendToDLQ({
 });
 ```
 
-## Comportamento de entrega
-
-### Falha de rede ou API indisponivel
+**Parâmetros do `ReboundClient`:**
 
-Para erros transientes, o SDK continua aplicando retry em background com backoff exponencial.
+| Campo | Obrigatório | Descrição |
+|---|---|---|
+| `projectSecret` | ✅ Sim | Chave secreta do projeto, usada para autenticação e criptografia local. |
 
-### Conta liberada para overage
-
-Quando a conta pode cobrar uso extra, a ingestao continua normalmente e o excedente e faturado pela plataforma na fatura Stripe da conta.
-
-### Conta bloqueada por limite com `bill_extra` desativado
-
-Quando a conta opta por **nao exceder o limite**:
-
-- o SDK nao insiste em retry infinito para esse caso
-- o evento atual e descartado
-- novos eventos tambem sao descartados enquanto a conta continuar bloqueada
-- o SDK consulta o estado da conta periodicamente e volta a enviar sozinho quando ela se tornar elegivel de novo
-
-Esse comportamento existe para respeitar a decisao explicita da conta de nao gerar custo extra.
-
-### Conta bloqueada por limite, mas com escolha de `bill_extra`
-
-Quando a conta escolheu **aceitar cobranca extra** e a plataforma ainda responde com bloqueio temporario, o SDK assume que o cliente prefere **nao perder eventos** e usa um buffer temporario:
-
-- os eventos ficam em um `blocked buffer` em memoria por ate **15 minutos**
-- o buffer tem limite de **250 eventos por processo e por chave**
-- o SDK faz polling autenticado a cada **60 segundos**
-- quando a conta volta a ficar apta, os eventos buffered sao reenfileirados e enviados em ordem FIFO
-
-Se a conta continuar bloqueada alem da janela de buffer, os eventos buffered expiram e sao descartados com log explicito.
-
-## Observacao sobre `endpoint`
-
-Prefira informar o `endpoint` como **URL base da API**. Exemplo recomendado:
-
-```ts
-endpoint: 'https://sua-api.com/api/v1'
-```
-
-Tambem funciona por compatibilidade:
-
-```ts
-endpoint: 'https://sua-api.com/api/v1/dlq-injestion'
-```
-
-O SDK adiciona internamente:
-
-- `/dlq-injestion`
-- `/dlq-injestion/runtime-state`
-
-## Matriz de comportamento
-
-| Situacao | Comportamento do SDK |
-| --- | --- |
-| `2xx` da API | remove o item da fila |
-| falha de rede / `5xx` / erro transiente | retry com backoff exponencial |
-| limite de plano com politica `block` | descarta enquanto bloqueado e reconsulta estado |
-| limite de plano com escolha de `bill_extra`, mas bloqueio temporario | usa blocked buffer e reconsulta estado |
-| conta liberada novamente | retoma automaticamente sem reiniciar o processo |
-
-## O que o cliente precisa saber sobre limites e cobranca extra
-
-Nao existe parametro novo no SDK para habilitar esse comportamento. Ele depende da configuracao da conta no Rebound DLQ:
-
-- se a conta habilitar cobranca extra para eventos, a plataforma tenta continuar a ingestao e cobrar o excedente
-- se a conta desabilitar cobranca extra, o SDK entende que pode haver perda de dados acima do limite e passa a descartar enquanto durar o bloqueio
-- se a conta fizer upgrade ou alterar essa politica, o SDK detecta a mudanca automaticamente na proxima sincronizacao
-
-Em outras palavras: **a decisao de produto e da conta; o SDK apenas executa essa politica automaticamente**.
-
-## Observacoes operacionais importantes
-
-- a fila do SDK e **in-memory**
-- eventos pendentes ou buffered **nao sobrevivem** a restart do processo
-- workloads de curta duracao ou ambientes muito efemeros podem perder eventos se o processo encerrar logo apos o enqueue
-- para maior seguranca operacional, prefira rodar o SDK em processos com shutdown gracioso
-- o SDK registra logs no console quando entra em modo de retry, descarte, buffer e retomada
-
-## Compatibilidade com APIs antigas
-
-Se a API de destino ainda nao suportar o contrato estruturado de bloqueio por limite, o SDK continua tratando respostas nao `2xx` como erros retryaveis. Ou seja: o fluxo novo de `buffer` e `discard` depende da API estar atualizada.
-
-## FAQ rapido
+---
 
-### Preciso alterar meu codigo para usar o buffer ou o descarte?
+## Comportamento automático
 
-Nao. Esse comportamento e automatico nesta versao do SDK.
+O SDK gerencia entrega, retry e limites de plano de forma totalmente automática, sem configuração adicional.
 
-### Preciso informar um parametro novo no construtor?
+| Situação | O que o SDK faz |
+|---|---|
+| Sucesso na entrega | Remove o evento da fila |
+| Falha de rede / erro transiente | Retry com backoff exponencial |
+| Conta no limite (sem cobrança extra) | Descarta eventos e reconsulta o estado periodicamente |
+| Conta no limite (com cobrança extra ativa) | Mantém eventos em buffer por até 15 min e retenta quando liberado |
+| Conta desbloqueada / upgrade | Retoma o envio automaticamente, sem reiniciar o processo |
 
-Nao. Basta manter `projectSecret` e, se necessario, `endpoint`.
+> A política de limite e cobrança extra é definida na sua conta na plataforma, não no SDK.
 
-### O SDK vai me avisar quando a conta for desbloqueada?
+---
 
-Sim. Ele faz polling em background e retoma sozinho quando a API indicar que a conta voltou a poder ingerir eventos.
+## Observações operacionais
 
-### O buffer guarda tudo indefinidamente?
+- A fila é **in-memory**: eventos não sobrevivem a restart do processo.
+- Para workloads efêmeros, prefira processos com **shutdown gracioso**.
+- O SDK emite logs no console ao entrar em modo de retry, buffer ou descarte.
 
-Nao. Ele e temporario, fica apenas em memoria, dura ate 15 minutos e respeita o limite de 250 eventos por processo/chave.
+---
 
 ## Suporte
 
-Se voce tiver duvidas de integracao, comportamento de limites ou operacao do SDK, abra um chamado pela plataforma oficial da [Rebound DLQ](https://rebound-dlq.com).
+Dúvidas de integração ou comportamento? Abra um chamado pela plataforma oficial em [rebound-dlq.com](https://rebound-dlq.com).
 
 ---
+
 Feito por **Codify Labs / Rebound DLQ**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rebound-dlq/node",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": ["dist"],