@rebound-dlq/node 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# Rebound DLQ SDK 🚀
+
+O **Rebound DLQ SDK** é uma solução de altíssima performance (Zero Gargalos e Fila em Memória) para capturar falhas em integrações, proteger sua regra de negócio e fazer o reprocessamento de DLQs (Dead Letter Queues) de forma transparente para sua aplicação Node.js.
+
+Sua aplicação original não vai travar nem ficar lenta, mesmo se a nossa API cair ou a rede oscilar.
+
+## 📦 1. Instalação
+
+Abra o terminal do seu projeto Node.js e instale o pacote:
+
+```bash
+npm install @rebound/dlq-sdk
+```
+
+*(Nota: Se você está rodando um pacote em testes local via `.tgz`, use: `npm install ./caminho/do/seu/rebound-dlq-sdk-0.1.0.tgz`)*
+
+---
+
+## ⚙️ 2. Como Configurar e Usar na Prática
+
+A forma ideal de utilizar o SDK é "abraçando" (envolvendo) as funções de risco do seu sistema (pagamentos, cadastros em APIs externas, envio de emails, etc) através do `DlqWrapper`.
+
+### Passo A: Importar e Configurar o SDK
+
+No topo do seu arquivo principal (ou no seu arquivo de injeção de dependências), inicialize o Wrapper passando suas credenciais:
+
+```javascript
+// Se você usa CommonJS (require):
+const { DlqWrapper } = require('@rebound/dlq-sdk');
+
+// Se você usa ES Modules (import):
+// import { DlqWrapper } from '@rebound/dlq-sdk';
+
+const dlqWrapper = new DlqWrapper({
+  projectId: "seu-project-id", // Pegue no painel do Rebound
+  projectSecret: "sk_dev_sua_chave_secreta", // Use sk_dev_ para testes ou sk_live_ para produção
+});
+```
+
+### Passo B: Proteger sua Função
+
+Em vez de chamar sua função diretamente, chame ela *dentro* do método `.execute()` do SDK. 
+
+Sempre que a sua função der erro, o SDK silenciosamente vai capturar o payload e enviar pra Rebound em backgroud, enquanto sua aplicação segue a vida imediatamente e de forma limpa.
+
+```javascript
+// Uma função sua que costuma falhar ou chamar serviços externos
+async function minhaFuncaoDeRisco(dados) {
+    console.log("Iniciando pagamento...");
+    if (dados.valor > 1000) {
+        throw new Error("Saldo insuficiente na operadora do cartão");
+    }
+    return "Sucesso!";
+}
+
+async function run() {
+    // 1. Defina os dados que você quer salvar caso essa rotina falhe
+    const payloadQueSeraSalvoNaDLQ = { 
+        userId: "123", 
+        valor: 5000, 
+        tentativa: 1,
+        modulo: "Checkout"
+    };
+    
+    try {
+        // 2. Execute a sua função DENTRO da proteção do SDK
+        const resultado = await dlqWrapper.execute(
+            () => minhaFuncaoDeRisco(payloadQueSeraSalvoNaDLQ), // Sua função de negócio
+            payloadQueSeraSalvoNaDLQ // O Payload que vai pra nuvem em caso de erro
+        );
+        
+        console.log("Deu tudo certo:", resultado);
+
+    } catch (erro) {
+        // 3. Trate o erro localmente como você sempre fez (o App NÃO morre)
+        console.log("Erro na aplicação:", erro.message);
+        
+        // 🚀 A MÁGICA:
+        // Nesse exato momento, o SDK já pegou esse erro e despachou para o Rebound na nuvem.
+        // Se a internet falhou, ele salvou na memória RAM e ficará tentando de novo em background
+        // sem travar ou deixar sua API mais lenta!
+    }
+}
+
+run();
+```
+
+---
+
+## ⚡ Por que usar nossa DLQ Engine?
+
+1. **In-Memory Zero-Latency**: A comunicação com nossos servidores não engargala os verbos HTTP da sua aplicação. Assim que a exceção bater e você usar o wrapper, ele joga o payload rápido (`O(1)`) pra uma fila inteligente em Memória RAM da sua máquina.
+2. **Entrega Garantida**: Se a sua infra ou nossa nuvem apresentar lentidão, sua requisição fica salva temporariamente no Node Event Loop da sua aplicação fazendo "Retry Exponencial" silencioso.
+3. **Criptografia Automática**: Todas as requisições enviadas ao Painel são criptografadas (AES-256) com sua `projectSecret` ainda na sua infraestrutura. Ninguém acessa do outro lado além de você.
+
+### Modos suportados
+
+- `sk_dev_*` conectará automaticamente na Sandbox / Local (Porta 3001)
+- `sk_live_*` conectará aos endpoints oficiais estabilizados de produção.
+
+---
+**Suporte Rebound**  
+Dúvidas ou problemas? Acesse seu dashboard e abra um chamado com nosso time de engenharia.

package/dist/adapters/base.adapter.d.ts

@@ -0,0 +1,8 @@
+import { ReboundClient } from '../core/client';
+import { DLQPayload, SendToDLQOptions } from '../models/payload';
+export declare abstract class BaseAdapter {
+    protected client: ReboundClient;
+    constructor(client: ReboundClient);
+    sendToDLQ(options: SendToDLQOptions): Promise<void>;
+    protected normalizeError(error?: Error | string): DLQPayload['error'];
+}

package/dist/adapters/base.adapter.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseAdapter = void 0;
+class BaseAdapter {
+    constructor(client) {
+        this.client = client;
+    }
+    async sendToDLQ(options) {
+        const { payload, error, source = 'unknown', metadata = {} } = options;
+        const dlqPayload = {
+            payload,
+            source,
+            error: this.normalizeError(error),
+            metadata,
+            timestamp: Date.now()
+        };
+        return this.client.send(dlqPayload);
+    }
+    normalizeError(error) {
+        if (!error)
+            return undefined;
+        if (typeof error === 'string') {
+            return {
+                message: error,
+                name: 'Error'
+            };
+        }
+        return {
+            message: error.message,
+            stack: error.stack,
+            name: error.name,
+            code: error.code
+        };
+    }
+}
+exports.BaseAdapter = BaseAdapter;

package/dist/adapters/http.adapter.d.ts

@@ -0,0 +1,5 @@
+import { BaseAdapter } from './base.adapter';
+import { SendToDLQOptions } from '../models/payload';
+export declare class HTTPAdapter extends BaseAdapter {
+    sendToDLQ(options: SendToDLQOptions): Promise<void>;
+}

package/dist/adapters/http.adapter.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HTTPAdapter = void 0;
+const base_adapter_1 = require("./base.adapter");
+class HTTPAdapter extends base_adapter_1.BaseAdapter {
+    async sendToDLQ(options) {
+        return super.sendToDLQ({
+            ...options,
+            source: options.source || 'http',
+            metadata: {
+                ...options.metadata,
+                type: 'http'
+            }
+        });
+    }
+}
+exports.HTTPAdapter = HTTPAdapter;

package/dist/adapters/kafka.adapter.d.ts

@@ -0,0 +1,5 @@
+import { BaseAdapter } from './base.adapter';
+import { SendToDLQOptions } from '../models/payload';
+export declare class KafkaAdapter extends BaseAdapter {
+    sendToDLQ(options: SendToDLQOptions): Promise<void>;
+}

package/dist/adapters/kafka.adapter.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KafkaAdapter = void 0;
+const base_adapter_1 = require("./base.adapter");
+class KafkaAdapter extends base_adapter_1.BaseAdapter {
+    async sendToDLQ(options) {
+        return super.sendToDLQ({
+            ...options,
+            source: options.source || 'kafka',
+            metadata: {
+                ...options.metadata,
+                type: 'kafka'
+            }
+        });
+    }
+}
+exports.KafkaAdapter = KafkaAdapter;

package/dist/core/client.d.ts

@@ -0,0 +1,7 @@
+import { DLQPayload, ReboundConfig } from "../models/payload";
+export declare class ReboundClient {
+    private config;
+    private readonly baseUrl;
+    constructor(config: ReboundConfig);
+    send(payload: DLQPayload): Promise<void>;
+}

package/dist/core/client.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReboundClient = void 0;
+const constants_1 = require("./constants");
+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);
+    }
+    async send(payload) {
+        const endpoint = `${this.baseUrl}/dlq-injestion`;
+        const enrichedPayload = {
+            ...payload,
+            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);
+    }
+}
+exports.ReboundClient = ReboundClient;

package/dist/core/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const REBOUND_API_ENDPOINTS: {
+    readonly TEST: "http://localhost:3001/api/v1/test";
+    readonly PRODUCTION: "http://localhost:3001/api/v1";
+};

package/dist/core/constants.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REBOUND_API_ENDPOINTS = void 0;
+exports.REBOUND_API_ENDPOINTS = {
+    TEST: 'http://localhost:3001/api/v1/test',
+    PRODUCTION: 'http://localhost:3001/api/v1'
+};

package/dist/core/errors.d.ts

@@ -0,0 +1,7 @@
+export declare class ReboundError extends Error {
+    constructor(message: string);
+}
+export declare class ReboundAPIError extends ReboundError {
+    statusCode: number;
+    constructor(statusCode: number, message: string);
+}

package/dist/core/errors.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReboundAPIError = exports.ReboundError = void 0;
+class ReboundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ReboundError";
+    }
+}
+exports.ReboundError = ReboundError;
+class ReboundAPIError extends ReboundError {
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "ReboundAPIError";
+    }
+}
+exports.ReboundAPIError = ReboundAPIError;

package/dist/core/queue.d.ts

@@ -0,0 +1,12 @@
+export declare class MemoryQueue {
+    private static instance;
+    private queue;
+    private isProcessing;
+    private baseDelayMs;
+    private maxDelayMs;
+    private constructor();
+    static getInstance(): MemoryQueue;
+    enqueue(endpoint: string, apiKey: string, payload: any): void;
+    private processQueue;
+    private applyBackoff;
+}

package/dist/core/queue.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryQueue = void 0;
+class MemoryQueue {
+    constructor() {
+        this.queue = [];
+        this.isProcessing = false;
+        this.baseDelayMs = 1000;
+        this.maxDelayMs = 60000; // max 60 seconds between retries
+    }
+    static getInstance() {
+        if (!MemoryQueue.instance) {
+            MemoryQueue.instance = new MemoryQueue();
+        }
+        return MemoryQueue.instance;
+    }
+    enqueue(endpoint, apiKey, payload) {
+        this.queue.push({
+            endpoint,
+            apiKey,
+            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);
+        }
+    }
+    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
+                    this.queue.shift();
+                }
+                else {
+                    // API error (ex 429, 500)
+                    await this.applyBackoff(item);
+                }
+            }
+            catch (error) {
+                // Network unstable / Connection refused
+                await this.applyBackoff(item);
+            }
+        }
+        this.isProcessing = false;
+    }
+    async applyBackoff(item) {
+        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...`);
+        }
+        return new Promise((resolve) => setTimeout(resolve, delay));
+    }
+}
+exports.MemoryQueue = MemoryQueue;

package/dist/core/wrapper.d.ts

@@ -0,0 +1,17 @@
+export interface DlqServiceConfig {
+    projectId: string;
+    projectSecret: string;
+    endpoint?: string;
+    maxFailures?: number;
+}
+export declare class DlqWrapper {
+    private projectId;
+    private projectSecret;
+    private readonly endpoint;
+    constructor(config: DlqServiceConfig);
+    execute<T>(fn: () => Promise<T>, payload: any): Promise<T>;
+    private reportError;
+    private generateFingerprint;
+    private encrypt;
+    private sendToApi;
+}

package/dist/core/wrapper.js

@@ -0,0 +1,73 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DlqWrapper = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const constants_1 = require("./constants");
+const queue_1 = require("./queue");
+class DlqWrapper {
+    constructor(config) {
+        this.projectId = config.projectId;
+        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
+    }
+    async execute(fn, payload) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            // MemoryQueue handles retries in the background, making this instant
+            this.reportError(error, payload).catch(e => {
+                // Silently fail if reportError fails, so we don't block the client logic
+                console.error("[Rebound SDK] Error building payload to DLQ", e);
+            });
+            throw error;
+        }
+    }
+    async reportError(error, payload) {
+        const fingerprint = this.generateFingerprint(error);
+        const encryptedPayload = this.encrypt(payload);
+        const data = {
+            projectId: this.projectId,
+            fingerprint,
+            error: {
+                name: error.name,
+                message: error.message,
+                stack: error.stack
+            },
+            payload: encryptedPayload
+        };
+        return this.sendToApi(data);
+    }
+    generateFingerprint(error) {
+        const stack = (error.stack || "").split("\n").slice(0, 3).join("");
+        return crypto_1.default.createHash('sha256')
+            .update(`${error.name}${stack}`)
+            .digest('hex');
+    }
+    encrypt(payload) {
+        const algorithm = 'aes-256-cbc';
+        // Use projectSecret to derive a 32-byte key. 
+        // If it's not 32 bytes, we hash it to ensure it is.
+        const key = crypto_1.default.createHash('sha256').update(String(this.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');
+        // We return iv and encrypted data together, maybe separated by a colon
+        return `${iv.toString('hex')}:${encrypted}`;
+    }
+    async sendToApi(data) {
+        // Rely on MemoryQueue to guarantee delivery and offload network bottlenecks
+        queue_1.MemoryQueue.getInstance().enqueue(this.endpoint, this.projectSecret, data);
+    }
+}
+exports.DlqWrapper = DlqWrapper;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { ReboundClient } from './core/client';
+export { DlqWrapper } from './core/wrapper';
+export type { DlqServiceConfig } from './core/wrapper';
+export { HTTPAdapter } from './adapters/http.adapter';
+export { KafkaAdapter } from './adapters/kafka.adapter';
+export { ReboundError, ReboundAPIError } from './core/errors';
+export type { DLQPayload, ReboundConfig, SendToDLQOptions } from './models/payload';

package/dist/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ReboundAPIError = exports.ReboundError = exports.KafkaAdapter = exports.HTTPAdapter = exports.DlqWrapper = exports.ReboundClient = void 0;
+var client_1 = require("./core/client");
+Object.defineProperty(exports, "ReboundClient", { enumerable: true, get: function () { return client_1.ReboundClient; } });
+var wrapper_1 = require("./core/wrapper");
+Object.defineProperty(exports, "DlqWrapper", { enumerable: true, get: function () { return wrapper_1.DlqWrapper; } });
+var http_adapter_1 = require("./adapters/http.adapter");
+Object.defineProperty(exports, "HTTPAdapter", { enumerable: true, get: function () { return http_adapter_1.HTTPAdapter; } });
+var kafka_adapter_1 = require("./adapters/kafka.adapter");
+Object.defineProperty(exports, "KafkaAdapter", { enumerable: true, get: function () { return kafka_adapter_1.KafkaAdapter; } });
+var errors_1 = require("./core/errors");
+Object.defineProperty(exports, "ReboundError", { enumerable: true, get: function () { return errors_1.ReboundError; } });
+Object.defineProperty(exports, "ReboundAPIError", { enumerable: true, get: function () { return errors_1.ReboundAPIError; } });

package/dist/models/payload.d.ts

@@ -0,0 +1,23 @@
+export interface DLQPayload {
+    payload: any;
+    source: string;
+    error?: {
+        message: string;
+        stack?: string;
+        code?: string;
+        name?: string;
+    };
+    metadata?: Record<string, any>;
+    timestamp?: number;
+}
+export interface ReboundConfig {
+    apiKey: string;
+    endpoint?: string;
+    timeout?: number;
+}
+export interface SendToDLQOptions {
+    payload: any;
+    error?: Error | string;
+    source?: string;
+    metadata?: Record<string, any>;
+}

package/dist/models/payload.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@rebound-dlq/node",
+  "version": "0.1.0",
+  "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"
+  }
+}