@rebound-dlq/node 0.2.4 → 0.2.6

package/README.md

@@ -1,87 +1,84 @@
-# Rebound DLQ for Node.js
+# Rebound DLQ — Node.js SDK
 
 [![NPM Version](https://img.shields.io/npm/v/@rebound-dlq/node)](https://www.npmjs.com/package/@rebound-dlq/node)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-O **@rebound-dlq/node** e o SDK oficial em Node.js para integrar sua aplicacao com a plataforma **[Rebound DLQ](https://rebound-dlq.com)**.
+SDK oficial em Node.js para integrar sua aplicação com a plataforma **[Rebound DLQ](https://rebound-dlq.com)**.
 
-Ele captura falhas da sua aplicacao, criptografa o payload localmente e envia o evento para a sua conta em background, sem travar a regra de negocio. A fila e mantida em memoria e o SDK ja entende os cenarios de rede instavel, limite de plano, overage e retomada automatica apos upgrade ou mudanca de configuracao da conta.
+Capture falhas, registre eventos de erro e garanta rastreabilidade das suas filas mortas — tudo sem impactar a performance da sua aplicação.
 
-## Por que usar o Rebound DLQ?
+---
+
+## Por que usar?
+
+- **Zero 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.
 
-- **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.
+> **Pré-requisito:** uma conta e um projeto ativos em [rebound-dlq.com](https://rebound-dlq.com).
 
-> Importante: este SDK requer uma conta e um projeto ativos no Rebound DLQ.
+---
 
-## Instalacao
+## Instalação
 
 ```bash
 npm install @rebound-dlq/node
 ```
 
-## Requisitos
-
-Para usar o SDK com o comportamento completo desta versao:
-
-- uma chave valida do projeto
-- uma API Rebound atualizada, com suporte a:
-  - `POST /dlq-injestion`
-  - `POST /dlq-injestion/runtime-state`
-  - autenticacao HMAC com `x-api-key`, `x-sdk-timestamp` e `x-sdk-signature`
-  - resposta estruturada de bloqueio por limite de plano
+---
 
-Se voce usa a plataforma oficial atualizada da Rebound, nao precisa configurar nada extra no cliente para esse fluxo. O comportamento de buffer, descarte e retomada e automatico.
+## Configuração
 
-## Configuracao segura
+A única configuração obrigatória é o `projectSecret`, obtido no painel da plataforma Rebound DLQ.
 
-Nunca exponha a chave diretamente no codigo-fonte. Use variaveis de ambiente:
+Nunca exponha a chave no código-fonte. Use variáveis de ambiente:
 
 ```env
 REBOUND_PROJECT_SECRET="seu_project_secret_aqui"
 ```
 
-## Executando os examples do repositorio
+---
 
-Os arquivos em `examples/` foram deixados simples para teste local. Cada example tem duas variaveis no topo do arquivo:
+## Agrupamento por fluxo
 
-- `PROJECT_SECRET`
-- `API_ENDPOINT`
+Agora o SDK também pode ajudar a agrupar eventos DLQ por **fluxo de integração** na plataforma.
 
-Edite esses valores diretamente no arquivo que voce quer testar e depois rode o script.
+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.
 
-```bash
-npm run example:wrapper
-npm run example:http
-npm run example:kafka
-npm run example:internal
-```
+Os campos usados pela plataforma são:
 
-Se preferir, voce tambem pode chamar o runner diretamente:
+| 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`. |
 
-```bash
-node scripts/run-example.cjs wrapper
-```
+### Regra de agrupamento
 
-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`.
+- 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.
 
-### Fluxo unico de configuracao
+### Exemplo recomendado de nomenclatura
 
-O SDK agora trabalha com um fluxo unico:
+```ts
+{
+  flowKey: 'pagarme-payments',
+  flowLabel: 'Integração Pagarme',
+  flowStep: 'payment_webhook'
+}
+```
 
-- `projectSecret` para autenticar e derivar a criptografia local
-- `endpoint` para definir para qual API Rebound os eventos devem ser enviados
+> Dica: trate `flowKey` como identificador estável. Evite usar textos que mudam com frequência.
 
-Nao existe mais diferenca publica entre ambiente de teste e producao dentro do SDK. Se voce quiser apontar para outra API, basta informar `endpoint` explicitamente.
+---
 
-## Interfaces disponiveis
+## Interfaces disponíveis
 
-### 1. `DlqWrapper`
+### `DlqWrapper` — recomendado
 
-Melhor opcao para encapsular uma funcao que pode falhar.
+Encapsula qualquer função assíncrona. Se ela lançar uma exceção, o evento de erro é capturado, criptografado e enviado automaticamente em background.
 
 ```ts
 import { DlqWrapper } from '@rebound-dlq/node';
@@ -91,38 +88,21 @@ const dlq = new DlqWrapper({
 });
 ```
 
-#### 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. |
+**Parâmetros:**
 
-### 2. `ReboundClient`
+| Campo | Obrigatório | Descrição |
+|---|---|---|
+| `projectSecret` | ✅ Sim | Chave secreta do projeto, usada para autenticação e criptografia local. |
 
-Melhor opcao para enviar payloads DLQ manualmente ou usar os adapters.
+**Uso:**
 
 ```ts
-import { ReboundClient } from '@rebound-dlq/node';
-
-const client = new ReboundClient({
-  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
-  endpoint: process.env.REBOUND_API_ENDPOINT,
-});
+const resultado = await dlq.execute(() => minhaFuncaoQuePodefFalhar(dados), dados);
 ```
 
-#### Parametros
+O erro original é sempre relançado para o seu tratamento normal. O SDK apenas captura, criptografa e envia o evento em background.
 
-| 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`
+**Exemplo completo:**
 
 ```ts
 import { DlqWrapper } from '@rebound-dlq/node';
@@ -131,47 +111,56 @@ const dlq = new DlqWrapper({
   projectSecret: process.env.REBOUND_PROJECT_SECRET!,
 });
 
-async function processarPagamento(dados: {
-  userId: string;
-  valor: number;
-  tentativa: number;
-  modulo: string;
-}) {
-  if (dados.valor > 1000) {
-    throw new Error('Saldo insuficiente na operadora do cartao');
+async function processarPagamento(dados: { userId: string; valor: number }) {
+  if (dados.valor > 10000) {
+    throw new Error('Limite excedido na operadora');
   }
-
-  return 'Sucesso';
+  return 'aprovado';
 }
 
-async function main() {
-  const payload = {
-    userId: '123',
-    valor: 5000,
-    tentativa: 1,
-    modulo: 'Checkout',
-  };
-
-  try {
-    const resultado = await dlq.execute(() => processarPagamento(payload), payload);
-    console.log('Resultado:', resultado);
-  } catch (erro) {
-    console.error('Erro de negocio capturado pela aplicacao:', (erro as Error).message);
-  }
+try {
+  const resultado = await dlq.execute(
+    () => processarPagamento({ userId: 'u-123', valor: 15000 }),
+    { userId: 'u-123', valor: 15000 },
+  );
+} catch (err) {
+  // erro relançado normalmente — o SDK já registrou o evento
+  console.error((err as Error).message);
 }
+```
+
+### `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!,
+});
 
-main();
+await dlq.execute(
+  () => processarPagamento({ userId: 'u-123', valor: 15000 }),
+  {
+    userId: 'u-123',
+    valor: 15000,
+  },
+  {
+    flowKey: 'pagarme-payments',
+    flowLabel: 'Integração Pagarme',
+    flowStep: 'create_charge',
+  },
+);
 ```
 
-### O que acontece nesse fluxo
+> Se você não passar o terceiro parâmetro, o evento continua sendo enviado normalmente, sem vínculo com fluxo.
+
+---
 
-1. Sua funcao falha e a excecao e capturada.
-2. O payload e criptografado localmente com AES-256.
-3. O evento e colocado em uma fila em memoria.
-4. O SDK envia o evento em background com autenticacao HMAC.
-5. O erro original continua sendo relancado para o seu tratamento normal.
+### `ReboundClient` + adapters — uso avançado
 
-## Uso manual com `ReboundClient`
+Para enviar eventos manualmente ou usar com adapters (HTTP, Kafka etc.).
 
 ```ts
 import { ReboundClient, HTTPAdapter } from '@rebound-dlq/node';
@@ -183,123 +172,120 @@ const client = new ReboundClient({
 const httpDlq = new HTTPAdapter(client);
 
 await httpDlq.sendToDLQ({
-  payload: {
-    orderId: 'ORD-1001',
-    amount: 99.9,
-  },
+  payload: { orderId: 'ORD-1001', amount: 99.9 },
   error: new Error('Payment gateway timeout'),
+  flowKey: 'checkout-payments',
+  flowLabel: 'Checkout de pagamentos',
+  flowStep: 'gateway_authorization',
   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.
+**Parâmetros do `ReboundClient`:**
 
-### Conta liberada para overage
+| Campo | Obrigatório | Descrição |
+|---|---|---|
+| `projectSecret` | ✅ Sim | Chave secreta do projeto, usada para autenticação e criptografia local. |
 
-Quando a conta pode cobrar uso extra, a ingestao continua normalmente e o excedente e faturado pela plataforma na fatura Stripe da conta.
+### Exemplo com fluxo usando `HTTPAdapter`
 
-### 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.
+```ts
+import { ReboundClient, HTTPAdapter } from '@rebound-dlq/node';
 
-## Observacao sobre `endpoint`
+const client = new ReboundClient({
+  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
+});
 
-Prefira informar o `endpoint` como **URL base da API**. Exemplo recomendado:
+const httpDlq = new HTTPAdapter(client);
 
-```ts
-endpoint: 'https://sua-api.com/api/v1'
+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',
+  },
+});
 ```
 
-Tambem funciona por compatibilidade:
+### Exemplo com fluxo usando `KafkaAdapter`
 
 ```ts
-endpoint: 'https://sua-api.com/api/v1/dlq-injestion'
-```
-
-O SDK adiciona internamente:
-
-- `/dlq-injestion`
-- `/dlq-injestion/runtime-state`
-
-## Matriz de comportamento
+import { ReboundClient, KafkaAdapter } from '@rebound-dlq/node';
 
-| 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**.
+const client = new ReboundClient({
+  projectSecret: process.env.REBOUND_PROJECT_SECRET!,
+});
 
-## Observacoes operacionais importantes
+const kafkaDlq = new KafkaAdapter(client);
 
-- 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
+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',
+  },
+});
+```
 
-## Compatibilidade com APIs antigas
+### Resumo prático de uso
 
-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.
+- 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.
 
-## FAQ rapido
+---
 
-### Preciso alterar meu codigo para usar o buffer ou o descarte?
+## Comportamento automático
 
-Nao. Esse comportamento e automatico nesta versao do SDK.
+O SDK gerencia entrega, retry e limites de plano de forma totalmente automática, sem configuração adicional.
 
-### Preciso informar um parametro novo no construtor?
+| Situação | O que o SDK faz |
+|---|---|
+| Sucesso na entrega | Remove o evento da fila |
+| Falha de rede / erro transiente | Retry com backoff exponencial |
+| Conta no limite (sem cobrança extra) | Descarta eventos e reconsulta o estado periodicamente |
+| Conta no limite (com cobrança extra ativa) | Mantém eventos em buffer por até 15 min e retenta quando liberado |
+| Conta desbloqueada / upgrade | Retoma o envio automaticamente, sem reiniciar o processo |
 
-Nao. Basta manter `projectSecret` e, se necessario, `endpoint`.
+> A política de limite e cobrança extra é definida na sua conta na plataforma, não no SDK.
 
-### O SDK vai me avisar quando a conta for desbloqueada?
+---
 
-Sim. Ele faz polling em background e retoma sozinho quando a API indicar que a conta voltou a poder ingerir eventos.
+## Observações operacionais
 
-### O buffer guarda tudo indefinidamente?
+- A fila é **in-memory**: eventos não sobrevivem a restart do processo.
+- Para workloads efêmeros, prefira processos com **shutdown gracioso**.
+- O SDK emite logs no console ao entrar em modo de retry, buffer ou descarte.
 
-Nao. Ele e temporario, fica apenas em memoria, dura ate 15 minutos e respeita o limite de 250 eventos por processo/chave.
+---
 
 ## Suporte
 
-Se voce tiver duvidas de integracao, comportamento de limites ou operacao do SDK, abra um chamado pela plataforma oficial da [Rebound DLQ](https://rebound-dlq.com).
+Dúvidas de integração ou comportamento? Abra um chamado pela plataforma oficial em [rebound-dlq.com](https://rebound-dlq.com).
 
 ---
+
 Feito por **Codify Labs / Rebound DLQ**.

package/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.4",
+  "version": "0.2.6",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": ["dist"],