@rebound-dlq/node 0.2.5 → 0.2.6

package/README.md

@@ -40,6 +40,40 @@ REBOUND_PROJECT_SECRET="seu_project_secret_aqui"
 
 ---
 
+## Agrupamento por fluxo
+
+Agora o SDK também pode ajudar a agrupar eventos DLQ por **fluxo de integração** na plataforma.
+
+Isso é útil quando o seu cliente quer enxergar, por exemplo, apenas os erros do fluxo `Pagarme`, `ERP`, `Webhook de pedidos` ou qualquer outro processo operacional.
+
+Os campos usados pela plataforma são:
+
+| Campo | Obrigatório | Descrição |
+|---|---|---|
+| `flowKey` | ✅ Sim | Identificador técnico e estável do fluxo. Ex.: `pagarme-payments`. |
+| `flowLabel` | Não | Nome amigável exibido no painel. Ex.: `Integração Pagarme`. |
+| `flowStep` | Não | Etapa específica do fluxo. Ex.: `create_charge`, `payment_webhook`, `capture_receivables`. |
+
+### Regra de agrupamento
+
+- Se chegar um evento com um `flowKey` já existente naquele projeto, ele é agrupado no mesmo fluxo.
+- Se o `flowKey` ainda não existir, a plataforma cria o fluxo automaticamente.
+- Se o evento não enviar dados de fluxo, ele continua funcionando normalmente, como já funciona hoje.
+
+### Exemplo recomendado de nomenclatura
+
+```ts
+{
+  flowKey: 'pagarme-payments',
+  flowLabel: 'Integração Pagarme',
+  flowStep: 'payment_webhook'
+}
+```
+
+> Dica: trate `flowKey` como identificador estável. Evite usar textos que mudam com frequência.
+
+---
+
 ## Interfaces disponíveis
 
 ### `DlqWrapper` — recomendado
@@ -95,6 +129,33 @@ try {
 }
 ```
 
+### `DlqWrapper` com fluxo
+
+Se você quiser agrupar o evento por fluxo usando o `DlqWrapper`, passe um terceiro parâmetro opcional com o contexto do fluxo.
+
+```ts
+import { DlqWrapper } from '@rebound-dlq/node';
+
+const dlq = new DlqWrapper({
+  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
+});
+
+await dlq.execute(
+  () => processarPagamento({ userId: 'u-123', valor: 15000 }),
+  {
+    userId: 'u-123',
+    valor: 15000,
+  },
+  {
+    flowKey: 'pagarme-payments',
+    flowLabel: 'Integração Pagarme',
+    flowStep: 'create_charge',
+  },
+);
+```
+
+> Se você não passar o terceiro parâmetro, o evento continua sendo enviado normalmente, sem vínculo com fluxo.
+
 ---
 
 ### `ReboundClient` + adapters — uso avançado
@@ -113,11 +174,14 @@ const httpDlq = new HTTPAdapter(client);
 await httpDlq.sendToDLQ({
   payload: { orderId: 'ORD-1001', amount: 99.9 },
   error: new Error('Payment gateway timeout'),
+  flowKey: 'checkout-payments',
+  flowLabel: 'Checkout de pagamentos',
+  flowStep: 'gateway_authorization',
   metadata: {
     endpoint: '/api/payments',
     method: 'POST',
     tenantId: 'acme',
-  },
+  }
 });
 ```
 
@@ -127,6 +191,71 @@ await httpDlq.sendToDLQ({
 |---|---|---|
 | `projectSecret` | ✅ Sim | Chave secreta do projeto, usada para autenticação e criptografia local. |
 
+### Exemplo com fluxo usando `HTTPAdapter`
+
+```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,
+    customerId: 'cus_123',
+  },
+  error: new Error('Payment gateway timeout'),
+  flowKey: 'pagarme-payments',
+  flowLabel: 'Integração Pagarme',
+  flowStep: 'create_charge',
+  metadata: {
+    endpoint: '/api/payments',
+    method: 'POST',
+    tenantId: 'acme',
+  },
+});
+```
+
+### Exemplo com fluxo usando `KafkaAdapter`
+
+```ts
+import { ReboundClient, KafkaAdapter } from '@rebound-dlq/node';
+
+const client = new ReboundClient({
+  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
+});
+
+const kafkaDlq = new KafkaAdapter(client);
+
+await kafkaDlq.sendToDLQ({
+  payload: {
+    topic: 'payments.events',
+    partition: 2,
+    key: 'order-1001',
+    message: { orderId: 'ORD-1001', status: 'failed' },
+  },
+  error: new Error('Kafka publish timeout'),
+  flowKey: 'pagarme-payments',
+  flowLabel: 'Integração Pagarme',
+  flowStep: 'payment_webhook',
+  metadata: {
+    topic: 'payments.events',
+    consumerGroup: 'payments-worker',
+  },
+});
+```
+
+### Resumo prático de uso
+
+- Use `DlqWrapper` quando quiser a integração mais simples possível.
+- Use `ReboundClient` + adapters quando quiser separar melhor `payload` e `metadata`.
+- Para agrupamento por fluxo, envie `flowKey`, `flowLabel` e `flowStep` como campos opcionais separados do payload.
+- `metadata` continua existindo para contexto técnico adicional, sem misturar regra de agrupamento com o payload do usuário.
+
 ---
 
 ## Comportamento automático

package/dist/adapters/base.adapter.js

@@ -6,13 +6,16 @@ class BaseAdapter {
         this.client = client;
     }
     async sendToDLQ(options) {
-        const { payload, error, source = 'unknown', metadata = {} } = options;
+        const { payload, error, source = 'unknown', metadata = {}, flowKey, flowLabel, flowStep } = options;
         const dlqPayload = {
             payload,
             source,
             error: this.normalizeError(error),
             metadata,
-            timestamp: Date.now()
+            timestamp: Date.now(),
+            flowKey,
+            flowLabel,
+            flowStep,
         };
         return this.client.send(dlqPayload);
     }

package/dist/core/client.d.ts

@@ -1,4 +1,4 @@
-import { DLQPayload, ReboundConfig } from "../models/payload";
+import { DLQPayload, ReboundConfig } from '../models/payload';
 export declare class ReboundClient {
     private config;
     private readonly baseUrl;
@@ -7,5 +7,7 @@ export declare class ReboundClient {
     private buildIngestionPayload;
     private normalizeError;
     private generateFingerprint;
+    private normalizeFlowContext;
+    private normalizeOptionalText;
     private encrypt;
 }

package/dist/core/client.js

@@ -28,10 +28,12 @@ class ReboundClient {
             metadata: payload.metadata ?? {},
             timestamp: payload.timestamp || Date.now(),
         };
+        const flowContext = this.normalizeFlowContext(payload);
         return {
             fingerprint: this.generateFingerprint(normalizedError, payload.source),
             error: normalizedError,
             payload: this.encrypt(envelope),
+            ...flowContext,
         };
     }
     normalizeError(error) {
@@ -50,6 +52,24 @@ class ReboundClient {
         const seed = `${error?.name || 'UnknownError'}${error?.message || ''}${stack}${source}`;
         return crypto_1.default.createHash('sha256').update(seed).digest('hex');
     }
+    normalizeFlowContext(payload) {
+        const flowKey = this.normalizeOptionalText(payload.flowKey);
+        if (!flowKey) {
+            return {};
+        }
+        return {
+            flowKey,
+            flowLabel: this.normalizeOptionalText(payload.flowLabel),
+            flowStep: this.normalizeOptionalText(payload.flowStep),
+        };
+    }
+    normalizeOptionalText(value) {
+        if (typeof value !== 'string') {
+            return undefined;
+        }
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
     encrypt(payload) {
         const algorithm = 'aes-256-cbc';
         const key = crypto_1.default

package/dist/core/constants.d.ts

@@ -1 +1 @@
-export declare const DEFAULT_REBOUND_API_ENDPOINT = "http://localhost:3001/api/v1";
+export declare const DEFAULT_REBOUND_API_ENDPOINT = "https://api.rebound-dlq.com/api/v1";

package/dist/core/constants.js

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

package/dist/core/wrapper.d.ts

@@ -1,3 +1,4 @@
+import type { DlqFlowContext } from '../models/payload';
 export interface DlqServiceConfig {
     projectSecret: string;
     endpoint?: string;
@@ -7,9 +8,11 @@ export declare class DlqWrapper {
     private projectSecret;
     private readonly endpoint;
     constructor(config: DlqServiceConfig);
-    execute<T>(fn: () => Promise<T>, payload: any): Promise<T>;
+    execute<T>(fn: () => Promise<T>, payload: any, flow?: DlqFlowContext): Promise<T>;
     private reportError;
     private generateFingerprint;
+    private normalizeFlowContext;
+    private normalizeOptionalText;
     private encrypt;
     private sendToApi;
 }

package/dist/core/wrapper.js

@@ -14,22 +14,23 @@ class DlqWrapper {
         const configuredEndpoint = config.endpoint || constants_1.DEFAULT_REBOUND_API_ENDPOINT;
         this.endpoint = (0, endpoint_1.resolveDlqIngestionEndpoint)(configuredEndpoint);
     }
-    async execute(fn, payload) {
+    async execute(fn, payload, flow) {
         try {
             return await fn();
         }
         catch (error) {
             // MemoryQueue handles retries in the background, making this instant
-            this.reportError(error, payload).catch(e => {
+            this.reportError(error, payload, flow).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) {
+    async reportError(error, payload, flow) {
         const fingerprint = this.generateFingerprint(error);
         const encryptedPayload = this.encrypt(payload);
+        const normalizedFlow = this.normalizeFlowContext(flow);
         const data = {
             fingerprint,
             error: {
@@ -37,7 +38,8 @@ class DlqWrapper {
                 message: error.message,
                 stack: error.stack
             },
-            payload: encryptedPayload
+            payload: encryptedPayload,
+            ...normalizedFlow,
         };
         return this.sendToApi(data);
     }
@@ -47,6 +49,24 @@ class DlqWrapper {
             .update(`${error.name}${stack}`)
             .digest('hex');
     }
+    normalizeFlowContext(flow) {
+        const flowKey = this.normalizeOptionalText(flow?.flowKey);
+        if (!flowKey) {
+            return {};
+        }
+        return {
+            flowKey,
+            flowLabel: this.normalizeOptionalText(flow?.flowLabel),
+            flowStep: this.normalizeOptionalText(flow?.flowStep),
+        };
+    }
+    normalizeOptionalText(value) {
+        if (typeof value !== 'string') {
+            return undefined;
+        }
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : undefined;
+    }
     encrypt(payload) {
         const algorithm = 'aes-256-cbc';
         // Use projectSecret to derive a 32-byte key. 

package/dist/index.d.ts

@@ -4,4 +4,4 @@ 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';
+export type { DLQPayload, DlqFlowContext, ReboundConfig, SendToDLQOptions } from './models/payload';

package/dist/models/payload.d.ts

@@ -1,3 +1,8 @@
+export interface DlqFlowContext {
+    flowKey?: string;
+    flowLabel?: string;
+    flowStep?: string;
+}
 export interface DLQPayload {
     payload: any;
     source: string;
@@ -9,13 +14,16 @@ export interface DLQPayload {
     };
     metadata?: Record<string, any>;
     timestamp?: number;
+    flowKey?: string;
+    flowLabel?: string;
+    flowStep?: string;
 }
 export interface ReboundConfig {
     projectSecret: string;
     endpoint?: string;
     timeout?: number;
 }
-export interface SendToDLQOptions {
+export interface SendToDLQOptions extends DlqFlowContext {
     payload: any;
     error?: Error | string;
     source?: string;

package/package.json

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