@rebound-dlq/node 0.2.2 → 0.2.4

package/README.md

@@ -3,66 +3,149 @@
 [![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** é o SDK oficial em Node.js para integração com a plataforma **[Rebound DLQ](https://rebound-dlq.com)**.
+O **@rebound-dlq/node** e o SDK oficial em Node.js para integrar sua aplicacao com a plataforma **[Rebound DLQ](https://rebound-dlq.com)**.
 
-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.
+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.
 
 ## 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.
+- **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.
 
-> ⚠️ **Atenção**: Este SDK requer uma conta ativa na plataforma **[Rebound DLQ](https://rebound-dlq.com)**.
+> Importante: este SDK requer uma conta e um projeto ativos no Rebound DLQ.
 
-## Instalação
-
-Abra o terminal e instale o pacote via npm, yarn ou pnpm:
+## Instalacao
 
 ```bash
 npm install @rebound-dlq/node
 ```
 
-## Configuração Segura
+## 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
 
-O SDK só precisa da chave de integração do seu projeto (`projectSecret`). 
+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.
 
-**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`).
+## Configuracao segura
+
+Nunca exponha a chave diretamente no codigo-fonte. Use variaveis de ambiente:
 
 ```env
-# Arquivo .env
-REBOUND_PROJECT_SECRET="sk_dev_sua_chave_secreta_aqui"
+REBOUND_PROJECT_SECRET="seu_project_secret_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.
+## 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`
 
-## Uso Básico
+Edite esses valores diretamente no arquivo que voce quer testar e depois rode o script.
 
-A forma ideal de utilizar o SDK é encapsular a sua função com o método `.execute()` oferecido pela classe `DlqWrapper`. 
+```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
+```
 
-Se atente à inicialização e uso:
+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`.
 
-```typescript
+### 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
+
+### 1. `DlqWrapper`
+
+Melhor opcao para encapsular uma funcao que pode falhar.
+
+```ts
 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,
+  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
 });
+```
+
+#### Parametros
+
+| 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. |
+
+### 2. `ReboundClient`
 
-// A função que se conecta ao seu provedor ou ao seu banco de dados (que pode falhar)
-async function processarPagamento(dados) {
+Melhor opcao para enviar payloads DLQ manualmente ou usar os adapters.
+
+```ts
+import { ReboundClient } from '@rebound-dlq/node';
+
+const client = new ReboundClient({
+  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
+  endpoint: process.env.REBOUND_API_ENDPOINT,
+});
+```
+
+#### 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.
+
+## Uso recomendado com `DlqWrapper`
+
+```ts
+import { DlqWrapper } from '@rebound-dlq/node';
+
+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 cartão');
+    throw new Error('Saldo insuficiente na operadora do cartao');
   }
-  return 'Sucesso!';
+
+  return 'Sucesso';
 }
 
 async function main() {
-  // Os dados de contexto que você gostaria de analisar depois se algo der errado
-  const payloadQueSeraSalvoNaDLQ = {
+  const payload = {
     userId: '123',
     valor: 5000,
     tentativa: 1,
@@ -70,37 +153,153 @@ async function main() {
   };
 
   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);
-
+    const resultado = await dlq.execute(() => processarPagamento(payload), payload);
+    console.log('Resultado:', 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);
+    console.error('Erro de negocio capturado pela aplicacao:', (erro as Error).message);
   }
 }
 
 main();
 ```
 
-### O que acontece por baixo dos panos neste exemplo?
+### 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.
+
+## Uso manual com `ReboundClient`
+
+```ts
+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,
+  },
+  error: new Error('Payment gateway timeout'),
+  metadata: {
+    endpoint: '/api/payments',
+    method: 'POST',
+    tenantId: 'acme',
+  },
+});
+```
+
+## Comportamento de entrega
+
+### Falha de rede ou API indisponivel
+
+Para erros transientes, o SDK continua aplicando retry em background com backoff exponencial.
+
+### 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?
+
+Nao. Esse comportamento e automatico nesta versao do SDK.
+
+### Preciso informar um parametro novo no construtor?
+
+Nao. Basta manter `projectSecret` e, se necessario, `endpoint`.
+
+### 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.
+
+### O buffer guarda tudo indefinidamente?
 
-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.
+Nao. Ele e temporario, fica apenas em memoria, dura ate 15 minutos e respeita o limite de 250 eventos por processo/chave.
 
 ## Suporte
 
-Em caso de dúvidas, problemas de implementação ou bugs, abra um chamado pela Dashboard oficial do [Rebound Platform](https://rebound-dlq.com).
+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).
 
-***
-_Feito com ❤️ por **[Codify Labs] / [Rebound DLQ]**._
+---
+Feito por **Codify Labs / Rebound DLQ**.

package/dist/adapters/base.adapter.js

@@ -29,7 +29,7 @@ class BaseAdapter {
             message: error.message,
             stack: error.stack,
             name: error.name,
-            code: error.code
+            code: error.code !== undefined ? String(error.code) : undefined
         };
     }
 }

package/dist/core/client.d.ts

@@ -4,4 +4,8 @@ export declare class ReboundClient {
     private readonly baseUrl;
     constructor(config: ReboundConfig);
     send(payload: DLQPayload): Promise<void>;
+    private buildIngestionPayload;
+    private normalizeError;
+    private generateFingerprint;
+    private encrypt;
 }

package/dist/core/client.js

@@ -1,25 +1,68 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ReboundClient = void 0;
+const crypto_1 = __importDefault(require("crypto"));
 const constants_1 = require("./constants");
+const endpoint_1 = require("./endpoint");
 const queue_1 = require("./queue");
 class ReboundClient {
     constructor(config) {
         this.config = config;
-        const isTest = config.apiKey.startsWith('sk_test_');
-        this.baseUrl = config.endpoint ||
-            (isTest
-                ? constants_1.REBOUND_API_ENDPOINTS.TEST
-                : constants_1.REBOUND_API_ENDPOINTS.PRODUCTION);
+        const configuredEndpoint = config.endpoint || constants_1.DEFAULT_REBOUND_API_ENDPOINT;
+        this.baseUrl = (0, endpoint_1.resolveDlqBaseEndpoint)(configuredEndpoint);
     }
     async send(payload) {
-        const endpoint = `${this.baseUrl}/dlq-injestion`;
-        const enrichedPayload = {
-            ...payload,
+        const endpoint = (0, endpoint_1.resolveDlqIngestionEndpoint)(this.baseUrl);
+        const ingestionPayload = this.buildIngestionPayload(payload);
+        // Enqueue directly in memory so the application doesn't block on network responses
+        queue_1.MemoryQueue.getInstance().enqueue(endpoint, this.config.projectSecret, ingestionPayload);
+    }
+    buildIngestionPayload(payload) {
+        const normalizedError = this.normalizeError(payload.error);
+        const envelope = {
+            payload: payload.payload,
+            source: payload.source,
+            metadata: payload.metadata ?? {},
             timestamp: payload.timestamp || Date.now(),
         };
-        // Enqueue directly in memory so the application doesn't block on network responses
-        queue_1.MemoryQueue.getInstance().enqueue(endpoint, this.config.apiKey, enrichedPayload);
+        return {
+            fingerprint: this.generateFingerprint(normalizedError, payload.source),
+            error: normalizedError,
+            payload: this.encrypt(envelope),
+        };
+    }
+    normalizeError(error) {
+        if (!error) {
+            return undefined;
+        }
+        return {
+            message: error.message,
+            stack: error.stack,
+            name: error.name,
+            code: error.code !== undefined ? String(error.code) : undefined,
+        };
+    }
+    generateFingerprint(error, source) {
+        const stack = (error?.stack || '').split('\n').slice(0, 3).join('');
+        const seed = `${error?.name || 'UnknownError'}${error?.message || ''}${stack}${source}`;
+        return crypto_1.default.createHash('sha256').update(seed).digest('hex');
+    }
+    encrypt(payload) {
+        const algorithm = 'aes-256-cbc';
+        const key = crypto_1.default
+            .createHash('sha256')
+            .update(String(this.config.projectSecret))
+            .digest('base64')
+            .substring(0, 32);
+        const iv = crypto_1.default.randomBytes(16);
+        const payloadString = typeof payload === 'string' ? payload : JSON.stringify(payload);
+        const cipher = crypto_1.default.createCipheriv(algorithm, Buffer.from(key), iv);
+        let encrypted = cipher.update(payloadString, 'utf8', 'hex');
+        encrypted += cipher.final('hex');
+        return `${iv.toString('hex')}:${encrypted}`;
     }
 }
 exports.ReboundClient = ReboundClient;

package/dist/core/constants.d.ts

@@ -1,4 +1 @@
-export declare const REBOUND_API_ENDPOINTS: {
-    readonly TEST: "https://rebound-dlq-api-2.vercel.app/api/v1";
-    readonly PRODUCTION: "https://rebound-dlq-api-2.vercel.app/api/v1";
-};
+export declare const DEFAULT_REBOUND_API_ENDPOINT = "http://localhost:3001/api/v1";

package/dist/core/constants.js

@@ -1,7 +1,4 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.REBOUND_API_ENDPOINTS = void 0;
-exports.REBOUND_API_ENDPOINTS = {
-    TEST: 'https://rebound-dlq-api-2.vercel.app/api/v1',
-    PRODUCTION: 'https://rebound-dlq-api-2.vercel.app/api/v1'
-};
+exports.DEFAULT_REBOUND_API_ENDPOINT = void 0;
+exports.DEFAULT_REBOUND_API_ENDPOINT = 'http://localhost:3001/api/v1';

package/dist/core/endpoint.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveDlqIngestionEndpoint(endpoint: string): string;
+export declare function resolveDlqBaseEndpoint(endpoint: string): string;

package/dist/core/endpoint.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveDlqIngestionEndpoint = resolveDlqIngestionEndpoint;
+exports.resolveDlqBaseEndpoint = resolveDlqBaseEndpoint;
+const DLQ_INGESTION_SEGMENT = '/dlq-injestion';
+function resolveDlqIngestionEndpoint(endpoint) {
+    const normalizedEndpoint = endpoint.replace(/\/+$/, '');
+    if (normalizedEndpoint.endsWith(DLQ_INGESTION_SEGMENT)) {
+        return normalizedEndpoint;
+    }
+    return `${normalizedEndpoint}${DLQ_INGESTION_SEGMENT}`;
+}
+function resolveDlqBaseEndpoint(endpoint) {
+    const normalizedEndpoint = endpoint.replace(/\/+$/, '');
+    if (normalizedEndpoint.endsWith(DLQ_INGESTION_SEGMENT)) {
+        return normalizedEndpoint.slice(0, -DLQ_INGESTION_SEGMENT.length);
+    }
+    return normalizedEndpoint;
+}

package/dist/core/queue.d.ts

@@ -2,11 +2,34 @@ export declare class MemoryQueue {
     private static instance;
     private queue;
     private isProcessing;
+    private isProcessingScheduled;
     private baseDelayMs;
     private maxDelayMs;
+    private blockedStates;
     private constructor();
     static getInstance(): MemoryQueue;
-    enqueue(endpoint: string, apiKey: string, payload: any): void;
+    enqueue(endpoint: string, projectSecret: string, payload: any): void;
     private processQueue;
     private applyBackoff;
+    private ensureProcessing;
+    private sendSignedJsonRequest;
+    private parseBlockedResponse;
+    private normalizeBlockedPayload;
+    private activateBlockedState;
+    private routeBlockedItem;
+    private bufferItem;
+    private pruneExpiredBufferedItems;
+    private scheduleProbe;
+    private probeBlockedState;
+    private fetchRuntimeState;
+    private normalizeRuntimeStateResponse;
+    private resumeBlockedState;
+    private logBlockedMode;
+    private buildQueueKey;
+    private buildRuntimeStateEndpoint;
+    private normalizeRecheckAfterMs;
+    private normalizeBufferWindowMs;
+    private isJsonResponse;
+    private isRecord;
+    private buildRetryWarning;
 }

package/dist/core/queue.js

@@ -1,12 +1,55 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MemoryQueue = void 0;
+const crypto = __importStar(require("crypto"));
+const DLQ_INGESTION_BLOCK_CODE = 'DLQ_INGESTION_BLOCKED_LIMIT';
+const DEFAULT_RECHECK_AFTER_MS = 60 * 1000;
+const DEFAULT_BUFFER_WINDOW_MS = 15 * 60 * 1000;
+const MIN_RECHECK_AFTER_MS = 15 * 1000;
+const MIN_BUFFER_WINDOW_MS = 60 * 1000;
+const MAX_BUFFER_WINDOW_MS = 60 * 60 * 1000;
+const MAX_BUFFERED_ITEMS_PER_KEY = 250;
 class MemoryQueue {
     constructor() {
         this.queue = [];
         this.isProcessing = false;
+        this.isProcessingScheduled = false;
         this.baseDelayMs = 1000;
         this.maxDelayMs = 60000; // max 60 seconds between retries
+        this.blockedStates = new Map();
     }
     static getInstance() {
         if (!MemoryQueue.instance) {
@@ -14,61 +57,330 @@ class MemoryQueue {
         }
         return MemoryQueue.instance;
     }
-    enqueue(endpoint, apiKey, payload) {
-        this.queue.push({
+    enqueue(endpoint, projectSecret, payload) {
+        const item = {
             endpoint,
-            apiKey,
+            projectSecret,
             payload,
             retryCount: 0
-        });
-        if (!this.isProcessing) {
-            // Offload to Event Loop so it returns instantly for the main application thread
-            setTimeout(() => {
-                this.processQueue().catch((err) => {
-                    console.error('[Rebound SDK] Unexpected queue error:', err);
-                });
-            }, 0);
+        };
+        const queueKey = this.buildQueueKey(endpoint, projectSecret);
+        const blockedState = this.blockedStates.get(queueKey);
+        if (blockedState) {
+            this.routeBlockedItem(item, blockedState);
+            this.scheduleProbe(queueKey, blockedState);
+            return;
         }
+        this.queue.push(item);
+        this.ensureProcessing();
     }
     async processQueue() {
         this.isProcessing = true;
-        while (this.queue.length > 0) {
-            const item = this.queue[0]; // FIFO
-            try {
-                const response = await fetch(item.endpoint, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        'x-api-key': `Bearer ${item.apiKey}`
-                    },
-                    body: JSON.stringify(item.payload),
-                });
-                if (response.ok) {
-                    if (item.retryCount > 0) {
-                        console.log(`[Rebound SDK] Event successfully delivered after ${item.retryCount} retries.`);
-                    }
-                    // Success: Remove item from memory queue
+        try {
+            while (this.queue.length > 0) {
+                const item = this.queue[0]; // FIFO
+                const queueKey = this.buildQueueKey(item.endpoint, item.projectSecret);
+                const blockedState = this.blockedStates.get(queueKey);
+                if (blockedState) {
                     this.queue.shift();
+                    this.routeBlockedItem(item, blockedState);
+                    this.scheduleProbe(queueKey, blockedState);
+                    continue;
                 }
-                else {
-                    // API error (ex 429, 500)
-                    await this.applyBackoff(item);
+                try {
+                    const response = await this.sendSignedJsonRequest(item.endpoint, item.projectSecret, item.payload);
+                    if (response.ok) {
+                        if (item.retryCount > 0) {
+                            console.log(`[Rebound SDK] Event successfully delivered after ${item.retryCount} retries.`);
+                        }
+                        this.queue.shift();
+                        continue;
+                    }
+                    const blockedResponse = await this.parseBlockedResponse(response);
+                    if (blockedResponse) {
+                        this.queue.shift();
+                        this.activateBlockedState(item, blockedResponse);
+                        continue;
+                    }
+                    await this.applyBackoff(item, {
+                        reason: 'http',
+                        statusCode: response.status,
+                    });
+                }
+                catch (error) {
+                    // Network unstable / Connection refused
+                    await this.applyBackoff(item, { reason: 'network' });
                 }
-            }
-            catch (error) {
-                // Network unstable / Connection refused
-                await this.applyBackoff(item);
             }
         }
-        this.isProcessing = false;
+        finally {
+            this.isProcessing = false;
+        }
     }
-    async applyBackoff(item) {
+    async applyBackoff(item, context) {
         item.retryCount++;
         const delay = Math.min(this.baseDelayMs * Math.pow(2, item.retryCount), this.maxDelayMs);
         if (item.retryCount === 1) {
-            console.warn(`[Rebound SDK] Connectivity issue sending DLQ event. Retrying in background to guarantee delivery...`);
+            console.warn(this.buildRetryWarning(context));
         }
         return new Promise((resolve) => setTimeout(resolve, delay));
     }
+    ensureProcessing() {
+        if (this.isProcessing || this.isProcessingScheduled) {
+            return;
+        }
+        this.isProcessingScheduled = true;
+        // Offload to Event Loop so it returns instantly for the main application thread
+        setTimeout(() => {
+            this.isProcessingScheduled = false;
+            this.processQueue().catch((err) => {
+                console.error('[Rebound SDK] Unexpected queue error:', err);
+            });
+        }, 0);
+    }
+    async sendSignedJsonRequest(endpoint, projectSecret, payload) {
+        const timestamp = Date.now().toString();
+        const payloadString = JSON.stringify(payload);
+        const dataToSign = `${timestamp}.${payloadString}`;
+        const signature = crypto
+            .createHmac('sha256', projectSecret)
+            .update(dataToSign)
+            .digest('hex');
+        return fetch(endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-api-key': `Bearer ${projectSecret}`,
+                'x-sdk-timestamp': timestamp,
+                'x-sdk-signature': signature
+            },
+            body: payloadString,
+        });
+    }
+    async parseBlockedResponse(response) {
+        if (response.status !== 403 || !this.isJsonResponse(response)) {
+            return null;
+        }
+        try {
+            const payload = await response.json();
+            return this.normalizeBlockedPayload(payload);
+        }
+        catch {
+            return null;
+        }
+    }
+    normalizeBlockedPayload(payload) {
+        if (!this.isRecord(payload)) {
+            return null;
+        }
+        if (payload.code !== DLQ_INGESTION_BLOCK_CODE || payload.retryable !== false) {
+            return null;
+        }
+        const queueAction = payload.queueAction === 'buffer' ? 'buffer' : 'discard';
+        const bufferWindowMs = queueAction === 'buffer'
+            ? this.normalizeBufferWindowMs(payload.bufferWindowSeconds)
+            : 0;
+        return {
+            queueAction,
+            bufferWindowMs,
+            recheckAfterMs: this.normalizeRecheckAfterMs(payload.recheckAfterSeconds),
+            currentPeriodEnd: typeof payload.currentPeriodEnd === 'string' ? payload.currentPeriodEnd : null,
+        };
+    }
+    activateBlockedState(item, payload) {
+        const queueKey = this.buildQueueKey(item.endpoint, item.projectSecret);
+        const previousState = this.blockedStates.get(queueKey) ?? null;
+        const previousAction = previousState?.queueAction ?? null;
+        const blockedState = previousState ?? {
+            endpoint: item.endpoint,
+            projectSecret: item.projectSecret,
+            queueAction: payload.queueAction,
+            bufferWindowMs: payload.bufferWindowMs,
+            recheckAfterMs: payload.recheckAfterMs,
+            currentPeriodEnd: payload.currentPeriodEnd,
+            buffer: [],
+            timer: null,
+            probeInFlight: false,
+        };
+        blockedState.queueAction = payload.queueAction;
+        blockedState.bufferWindowMs = payload.bufferWindowMs;
+        blockedState.recheckAfterMs = payload.recheckAfterMs;
+        blockedState.currentPeriodEnd = payload.currentPeriodEnd;
+        if (blockedState.queueAction === 'discard' && blockedState.buffer.length > 0) {
+            blockedState.buffer = [];
+        }
+        this.blockedStates.set(queueKey, blockedState);
+        this.routeBlockedItem(item, blockedState);
+        this.scheduleProbe(queueKey, blockedState);
+        if (!previousState || previousAction !== blockedState.queueAction) {
+            this.logBlockedMode(blockedState);
+        }
+    }
+    routeBlockedItem(item, blockedState) {
+        if (blockedState.queueAction === 'buffer') {
+            this.bufferItem(blockedState, item);
+            return;
+        }
+    }
+    bufferItem(blockedState, item) {
+        this.pruneExpiredBufferedItems(blockedState);
+        blockedState.buffer.push({
+            ...item,
+            expiresAt: Date.now() + blockedState.bufferWindowMs,
+        });
+        if (blockedState.buffer.length <= MAX_BUFFERED_ITEMS_PER_KEY) {
+            return;
+        }
+        const overflowCount = blockedState.buffer.length - MAX_BUFFERED_ITEMS_PER_KEY;
+        blockedState.buffer.splice(0, overflowCount);
+        console.warn(`[Rebound SDK] Buffer cap reached while DLQ ingestion is blocked. Dropped ${overflowCount} older buffered event(s).`);
+    }
+    pruneExpiredBufferedItems(blockedState) {
+        const now = Date.now();
+        const originalLength = blockedState.buffer.length;
+        blockedState.buffer = blockedState.buffer.filter((item) => item.expiresAt > now);
+        const droppedCount = originalLength - blockedState.buffer.length;
+        if (droppedCount > 0) {
+            console.warn(`[Rebound SDK] Dropped ${droppedCount} buffered event(s) after the temporary blocked window expired.`);
+        }
+    }
+    scheduleProbe(queueKey, blockedState) {
+        if (blockedState.timer) {
+            return;
+        }
+        blockedState.timer = setTimeout(() => {
+            blockedState.timer = null;
+            this.probeBlockedState(queueKey).catch((error) => {
+                console.error('[Rebound SDK] Failed to refresh blocked ingestion state:', error);
+            });
+        }, blockedState.recheckAfterMs);
+    }
+    async probeBlockedState(queueKey) {
+        const blockedState = this.blockedStates.get(queueKey);
+        if (!blockedState || blockedState.probeInFlight) {
+            return;
+        }
+        blockedState.probeInFlight = true;
+        try {
+            this.pruneExpiredBufferedItems(blockedState);
+            const runtimeState = await this.fetchRuntimeState(blockedState);
+            if (!runtimeState) {
+                return;
+            }
+            if (runtimeState.allowed) {
+                this.resumeBlockedState(queueKey, blockedState);
+                return;
+            }
+            const previousAction = blockedState.queueAction;
+            blockedState.queueAction = runtimeState.queueAction;
+            blockedState.bufferWindowMs = runtimeState.bufferWindowMs;
+            blockedState.recheckAfterMs = runtimeState.recheckAfterMs;
+            blockedState.currentPeriodEnd = runtimeState.currentPeriodEnd;
+            if (blockedState.queueAction === 'discard' && blockedState.buffer.length > 0) {
+                blockedState.buffer = [];
+            }
+            if (previousAction !== blockedState.queueAction) {
+                this.logBlockedMode(blockedState);
+            }
+        }
+        finally {
+            blockedState.probeInFlight = false;
+            if (this.blockedStates.has(queueKey)) {
+                this.scheduleProbe(queueKey, blockedState);
+            }
+        }
+    }
+    async fetchRuntimeState(blockedState) {
+        const response = await this.sendSignedJsonRequest(this.buildRuntimeStateEndpoint(blockedState.endpoint), blockedState.projectSecret, {});
+        if (!response.ok || !this.isJsonResponse(response)) {
+            return null;
+        }
+        try {
+            const payload = await response.json();
+            return this.normalizeRuntimeStateResponse(payload);
+        }
+        catch {
+            return null;
+        }
+    }
+    normalizeRuntimeStateResponse(payload) {
+        if (!this.isRecord(payload) || typeof payload.allowed !== 'boolean') {
+            return null;
+        }
+        if (payload.allowed) {
+            return {
+                allowed: true,
+                queueAction: 'discard',
+                bufferWindowMs: 0,
+                recheckAfterMs: this.normalizeRecheckAfterMs(payload.recheckAfterSeconds),
+                currentPeriodEnd: typeof payload.currentPeriodEnd === 'string' ? payload.currentPeriodEnd : null,
+            };
+        }
+        const blockedPayload = this.normalizeBlockedPayload(payload);
+        if (!blockedPayload) {
+            return null;
+        }
+        return {
+            allowed: false,
+            ...blockedPayload,
+        };
+    }
+    resumeBlockedState(queueKey, blockedState) {
+        this.blockedStates.delete(queueKey);
+        if (blockedState.timer) {
+            clearTimeout(blockedState.timer);
+            blockedState.timer = null;
+        }
+        this.pruneExpiredBufferedItems(blockedState);
+        if (blockedState.buffer.length > 0) {
+            const bufferedItems = blockedState.buffer.map(({ expiresAt, ...item }) => item);
+            this.queue = [...bufferedItems, ...this.queue];
+            console.log(`[Rebound SDK] DLQ ingestion resumed. Replaying ${bufferedItems.length} buffered event(s).`);
+        }
+        if (this.queue.length > 0) {
+            this.ensureProcessing();
+        }
+    }
+    logBlockedMode(blockedState) {
+        const cycleHint = blockedState.currentPeriodEnd
+            ? ` Current cycle ends at ${blockedState.currentPeriodEnd}.`
+            : '';
+        if (blockedState.queueAction === 'buffer') {
+            const bufferMinutes = Math.round(blockedState.bufferWindowMs / 60000);
+            console.warn(`[Rebound SDK] DLQ ingestion is temporarily blocked by the account plan. Buffering events for up to ${bufferMinutes} minute(s) while the account plan or billing settings are adjusted.${cycleHint}`);
+            return;
+        }
+        console.warn(`[Rebound SDK] DLQ ingestion is blocked by the account plan and extra usage is disabled. New events will be discarded until the account becomes eligible again.${cycleHint}`);
+    }
+    buildQueueKey(endpoint, projectSecret) {
+        return `${endpoint}::${projectSecret}`;
+    }
+    buildRuntimeStateEndpoint(endpoint) {
+        return `${endpoint.replace(/\/+$/, '')}/runtime-state`;
+    }
+    normalizeRecheckAfterMs(value) {
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            return DEFAULT_RECHECK_AFTER_MS;
+        }
+        return Math.max(Math.trunc(value * 1000), MIN_RECHECK_AFTER_MS);
+    }
+    normalizeBufferWindowMs(value) {
+        if (typeof value !== 'number' || !Number.isFinite(value)) {
+            return DEFAULT_BUFFER_WINDOW_MS;
+        }
+        return Math.min(Math.max(Math.trunc(value * 1000), MIN_BUFFER_WINDOW_MS), MAX_BUFFER_WINDOW_MS);
+    }
+    isJsonResponse(response) {
+        return (response.headers.get('content-type') ?? '').includes('application/json');
+    }
+    isRecord(value) {
+        return typeof value === 'object' && value !== null;
+    }
+    buildRetryWarning(context) {
+        if (context.reason === 'http' && context.statusCode) {
+            return `[Rebound SDK] DLQ API rejected the event with HTTP ${context.statusCode}. Retrying in background while the issue persists...`;
+        }
+        return '[Rebound SDK] Connectivity issue sending DLQ event. Retrying in background to guarantee delivery...';
+    }
 }
 exports.MemoryQueue = MemoryQueue;

package/dist/core/wrapper.js

@@ -6,16 +6,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DlqWrapper = void 0;
 const crypto_1 = __importDefault(require("crypto"));
 const constants_1 = require("./constants");
+const endpoint_1 = require("./endpoint");
 const queue_1 = require("./queue");
 class DlqWrapper {
     constructor(config) {
         this.projectSecret = config.projectSecret;
-        // Identifica se é ambiente de teste através do projectSecret (mesma lógica da apiKey no ReboundClient)
-        const isTest = config.projectSecret.startsWith('sk_dev_');
-        this.endpoint = config.endpoint ||
-            (isTest
-                ? constants_1.REBOUND_API_ENDPOINTS.TEST
-                : constants_1.REBOUND_API_ENDPOINTS.PRODUCTION) + '/dlq-injestion'; // Usar o sufixo apropriado
+        const configuredEndpoint = config.endpoint || constants_1.DEFAULT_REBOUND_API_ENDPOINT;
+        this.endpoint = (0, endpoint_1.resolveDlqIngestionEndpoint)(configuredEndpoint);
     }
     async execute(fn, payload) {
         try {

package/dist/models/payload.d.ts

@@ -11,7 +11,7 @@ export interface DLQPayload {
     timestamp?: number;
 }
 export interface ReboundConfig {
-    apiKey: string;
+    projectSecret: string;
     endpoint?: string;
     timeout?: number;
 }

package/package.json

@@ -1,18 +1,23 @@
-{
-  "name": "@rebound-dlq/node",
-  "version": "0.2.2",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "files": ["dist"],
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "json-server": "npx json-server --watch mock-server.json --port 3005",
-    "test:wrapper": "npx ts-node examples/wrapper-example.ts"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "json-server": "^1.0.0-beta.3",
-    "typescript": "^5.0.0"
-  }
-}
+{
+  "name": "@rebound-dlq/node",
+  "version": "0.2.4",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "build:examples": "node scripts/run-example.cjs --build-only",
+    "dev": "tsc --watch",
+    "json-server": "npx json-server --watch mock-server.json --port 3005",
+    "example:wrapper": "node scripts/run-example.cjs wrapper-example",
+    "example:http": "node scripts/run-example.cjs http-example",
+    "example:kafka": "node scripts/run-example.cjs kafka-example",
+    "example:internal": "node scripts/run-example.cjs internal-errors-example",
+    "test:wrapper": "node scripts/run-example.cjs wrapper-example"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "json-server": "^1.0.0-beta.3",
+    "typescript": "^5.0.0"
+  }
+}