@rebound-dlq/node 0.2.3 → 0.2.5

package/README.md

@@ -1,106 +1,162 @@
-# 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** é o SDK oficial em Node.js para integração 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)**.
 
-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.
+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?
+---
 
-- ⚡ **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.
+## Por que usar?
 
-> ⚠️ **Atenção**: Este SDK requer uma conta ativa na plataforma **[Rebound DLQ](https://rebound-dlq.com)**.
+- **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.
 
-## Instalação
+> **Pré-requisito:** uma conta e um projeto ativos em [rebound-dlq.com](https://rebound-dlq.com).
+
+---
 
-Abra o terminal e instale o pacote via npm, yarn ou pnpm:
+## Instalação
 
 ```bash
 npm install @rebound-dlq/node
 ```
 
-## Configuração Segura
+---
 
-O SDK só precisa da chave de integração do seu projeto (`projectSecret`). 
+## Configuração
 
-**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`).
+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:
 
 ```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.
+---
 
-## Uso Básico
+## Interfaces disponíveis
 
-A forma ideal de utilizar o SDK é encapsular a sua função com o método `.execute()` oferecido pela classe `DlqWrapper`. 
+### `DlqWrapper` — recomendado
 
-Se atente à inicialização e uso:
+Encapsula qualquer função assíncrona. Se ela lançar uma exceção, o evento de erro é capturado, criptografado e enviado automaticamente em background.
 
-```typescript
+```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!,
 });
+```
+
+**Parâmetros:**
+
+| Campo | Obrigatório | Descrição |
+|---|---|---|
+| `projectSecret` | ✅ Sim | Chave secreta do projeto, usada para autenticação e criptografia local. |
+
+**Uso:**
+
+```ts
+const resultado = await dlq.execute(() => minhaFuncaoQuePodefFalhar(dados), dados);
+```
 
-// 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');
+O erro original é sempre relançado para o seu tratamento normal. O SDK apenas captura, criptografa e envia o evento em background.
+
+**Exemplo completo:**
+
+```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 }) {
+  if (dados.valor > 10000) {
+    throw new Error('Limite excedido na operadora');
   }
-  return 'Sucesso!';
+  return 'aprovado';
 }
 
-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);
-  }
+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();
+---
+
+### `ReboundClient` + adapters — uso avançado
+
+Para enviar eventos manualmente ou usar com adapters (HTTP, Kafka etc.).
+
+```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',
+  },
+});
 ```
 
-### O que acontece por baixo dos panos neste exemplo?
+**Parâmetros do `ReboundClient`:**
+
+| Campo | Obrigatório | Descrição |
+|---|---|---|
+| `projectSecret` | ✅ Sim | Chave secreta do projeto, usada para autenticação e criptografia local. |
 
-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.
+---
+
+## 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 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 |
+
+> 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**.
+- O SDK emite logs no console ao entrar em modo de retry, buffer ou descarte.
+
+---
 
 ## 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).
+Dúvidas de integração ou comportamento? Abra um chamado pela plataforma oficial em [rebound-dlq.com](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://api.rebound-dlq.com/api/v1";
-    readonly PRODUCTION: "https://api.rebound-dlq.com/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://api.rebound-dlq.com/api/v1',
-    PRODUCTION: 'https://api.rebound-dlq.com/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

@@ -35,12 +35,21 @@ var __importStar = (this && this.__importStar) || (function () {
 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) {
@@ -48,70 +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 timestamp = Date.now().toString();
-                const payloadString = JSON.stringify(item.payload);
-                const dataToSign = `${timestamp}.${payloadString}`;
-                const signature = crypto
-                    .createHmac('sha256', item.apiKey)
-                    .update(dataToSign)
-                    .digest('hex');
-                const response = await fetch(item.endpoint, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'application/json',
-                        'x-api-key': `Bearer ${item.apiKey}`,
-                        'x-sdk-timestamp': timestamp,
-                        'x-sdk-signature': signature
-                    },
-                    body: payloadString,
-                });
-                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.3",
-  "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.5",
+  "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"
+  }
+}